bsls_ident

Macros
#define	BSLS_IDENT_OFF
#define	BSLS_IDENT(str)
#define	BSLS_IDENT(str)
#define	BSLS_IDENT_JOIN2(x, y)   x ## y
#define	BSLS_IDENT_JOIN(x, y)   BSLS_IDENT_JOIN2(x,y)
#define	BSLS_IDENT_RCSID(tag, str)    static char BSLS_IDENT_JOIN(ident_,tag)[] = str;
#define	BSLS_IDENT_RCSID(tag, str)
#define	BSLS_IDENT_PRAGMA_ONCE

Detailed Description

Outline

• Purpose
• Classes
• Macros
• Description
  • Macro Summary
  • Usage

Purpose

Provide macros for inserting SCM Ids into source files.

Classes

Macros

• BSLS_IDENT(identifier): inset identifier into .comment section
• BSLS_IDENT_RCSID(tag, identifier): alternatively, use add tag as static
• BSLS_IDENT_PRAGMA_ONCE: encapsulate _Pragma("once")

Description

The purpose of this component is to provide macros for inserting SCM (Source Control Management) Ids into source files. SCM Ids are useful for identifying source revisions in binaries. Additional information about SCM Ids may be obtained from the following man pages: man ident man strings (strings -a produces more verbose output) man mcs (Solaris-only)

Note that these SCM Ids are only present if the BSLS_IDENT_ON macro is defined at compilation time. By default, this macro is not defined, and ident strings are not added to object files.

SCM systems may replace Ids with their expanded forms. Note that we will replace the key symbol $ with (DOLLAR) to avoid any expansion within this header file's documentation.

SCM Ids usually take the form "(DOLLAR)Id: (DOLLAR)" which is expanded, automatically, by the source control system into an identifier which maps to specific source revision:

'(DOLLAR)Id: bsls_ident.h 141104 2010-09-17 00:30:47Z mgiroux (DOLLAR)'

This specifies that the file was checked in on 2010-09-17 at the specified time by user mgiroux, and can be retrieved from the SCM system using revision 141104.

BSLS_IDENT_PRAGMA_ONCE can optionally be used in headers and encapsulates a non-standard pragma (_Pragma("once")) supported on a number of platforms and which indicates that a header should only be included and parsed once. Use of this macro can help reduce compile times by eliminating extraneous I/O when headers are included more than once in the same translation unit. Note that this macro should not be used for any header that cannot use include guards: this is unusual, but can happen for certain low-level headers.

Macro Summary

The following are the macros provided by this component.

• BSLS_IDENT(identifier)

  ‍This macro inserts the specified identifier into the object's .comment section, if supported on the current platform.

• BSLS_IDENT_RCSID(tag, identifier)

  ‍This macro inserts the specified identifier into the object, using BSLS_IDENT, if possible on the current platform. If BSLS_IDENT is not available, the specified tag may be used to declare a static char array containing the tag.

• BSLS_IDENT_PRAGMA_ONCE

  ‍This macro encapsulates the _Pragma("once") functionality if available on the current platform. If available, this functions in the same way as redundant include guards, avoiding re-opening already-included header files.

Usage

Include bsls_ident.h and use the BSLS_IDENT macro. For header files this should be done directly after the include guards, e.g., bsls_somefile.h:

// bsls_somefile.h                                                -*-C++-*-
#ifndef INCLUDED_BSLS_SOMEFILE
#define INCLUDED_BSLS_SOMEFILE
 
#include <bsls_ident.h>
BSLS_IDENT("(DOLLAR)Id: (DOLLAR)") // In real usage, replace '(DOLLAR)'
                                   // with '$'
 
// ...
 
#endif // INCLUDED_BSLS_SOMEFILE

For cpp files it should be done directly after the comment for the file name and the language, e.g., bsls_somefile.cpp:

// bsls_ident.t.cpp                                               -*-C++-*-
 
#include <bsls_ident.h>
BSLS_IDENT("(DOLLAR)Id: (DOLLAR)") // In real usage, replace '(DOLLAR)'
                                   // with '$'

Macro Definition Documentation

BSLS_IDENT [1/2]

#define BSLS_IDENT

(

str

)

BSLS_IDENT [2/2]

#define BSLS_IDENT

(

str

)

BSLS_IDENT_JOIN

#define BSLS_IDENT_JOIN	(		x,
			y
	)		BSLS_IDENT_JOIN2(x,y)

BSLS_IDENT_JOIN2

#define BSLS_IDENT_JOIN2	(		x,
			y
	)		x ## y

BSLS_IDENT_OFF

#define BSLS_IDENT_OFF

BSLS_IDENT_PRAGMA_ONCE

#define BSLS_IDENT_PRAGMA_ONCE

BSLS_IDENT_RCSID [1/2]

#define BSLS_IDENT_RCSID	(		tag,
			str
	)		static char BSLS_IDENT_JOIN(ident_,tag)[] = str;

BSLS_IDENT_RCSID [2/2]

#define BSLS_IDENT_RCSID	(		tag,
			str
	)