FOG User Guide


Command Line

fog [options] [files]

An accurate list of options may be obtained by

    fog -help

The simplest usage

    fog source.file

works but is not recommended. It creates a pair of files class.hxx and class.cxx for each top-level class and namespace in the source file. (Templated classes get .H and .C extensions). Declarations for the global namespace are ignored.

It is recommended that generated files be placed in a separate directory (e.g. ./generated) by

    fog -hd generated -cd generated source.file

If global declarations are required, specify a name (e.g. global) for the unnamed namespace by adding

    -global global

Multiple source files are treated as the concatenation of those files. All are processed together.

If using NT, the following options will be necessary to enable inclusion of iostream

    "-ic:/Program Files/Microsoft Visual Studio/Vc98/Include" -D__cdecl= -D_WIN32 

If using SUN C++ 4.2, the corresponding options will be something like

    -i/opt/vws/c++3.0/SUNWspro/SC4.2/include/CC -long_long_type 

The full set of command line options is:

Miscellaneous options

-help		Display command line usage.
-q		Suppress the program identification message.

Preprocessor options

-D*		Define a preprocessor macro value.

The conventional NAME or NAME=5 options are supported for defining object-like macros. Definition of a function-like macro fails (a bug).

-I*		Source include file path(s) (defaults to current directory).
-i*		Source include file path(s) (defaults to current directory).

Variant C++ options

The default behaviour corresponds to standard C++. Some alternatives can be accommodated.

-long_long_type		Treat long long as built-in (Sun C++ language extension).
-mbc#			Bytes in a multi-byte character (4).
-no_access		Diagnose access declarations (ARM C++ compatibility).
-no_bool_type		Do not treat bool as built-in (ARM C++ compatibility).
-no_namespace		Treat namespace as a synonym for class.
-no_specialisation_prefix	Do not require "template<>" for specialisation (Pre-Ansi C++ compatibility).
-no_using		Emit using declarations as access declarations (ARM C++ compatibility).
-no_wchar_t_type	Do not treat wchar_t as built-in (ARM C++ compatibility).

Generated C++ options

-anon_prefix*		Prefix for "anonymous" names (default is "_anon_").
-comment_line_numbers	Enclose #line numbers as comments in emitted files.
-extern_prefix*		Prefix for "extern" linkage names (default is "_extern_").
-no_line_numbers	Omit #line numbers from emitted files.
-nobanner		Suppress emitted comment banners (to ease regression testing).
-t#			Columns per tab in source files (default 8).
-template_parameter_prefix*	Prefix for normalised template parameter names (default is "_").
-unnest			Emit nested classes after rather than within enclosing class.

Output file options

An emitted file name is formed as the concatenation of

<path> <separator> <prefix> <separator> <name> <suffix>

/ separators are omitted following blank paths or prefixes.
The path is empty by default, a specification is recommended.
The prefix is empty by default, and this is generally appropriate.
The name derives directly from the name of scope to be emitted.
The suffix defaults to .hxx/.cxx/.H or .C for implementation/interfaces of non-template/template scopes.

Unspecified paths and prefixes for templated scopes default to their non-template counterparts.

Unchanged output files are not overwritten to avoid tripping make unnecessarily unless -f is specified.

-cd*		Emitted implementation file directory path.
-cp*		Emitted implementation file prefix.
-cs*		Emitted implementation file suffix.
-ctd*		Emitted template implementation file directory path.
-ctp*		Emitted template implementation file prefix.
-cts*		Emitted template implementation file suffix.
-f		Force file emission (bypass redundancy comparisons).
-global*	(File)name of the global namespace.
-hd*		Emitted interface file directory path.
-hp*		Emitted interface file prefix.
-hs*		Emitted interface file suffix.
-htd*		Emitted template interface file directory path.
-htp*		Emitted template interface file prefix.
-hts*		Emitted template interface file suffix.
-log*		Log file name (duplicates standard error).
-nc		Notify emitted file names that are created.
-ne		Notify emitted file names that are suppressed through equivalence.
-o*		File name for make dependencies between source and emitted files.

Diagnostic options

-statistics	Emit program performance statistics.
-z2h		Display each token passed between lexer and hash parser.
-z2l		Display each token passed between lexer and replace parser.
-z2m		Display each token passed between lexer and main parser.
-z2r		Display each token passed between lexer and replace parser.
-z2s		Display each token passed between lexer and substitute parser.
-za		Display changes to the activity status of declarations.
-zd		Delete all objects rigorously on exit (for purify testing).
-zf		Display file name as each entity is (re)positioned.
-zi		Display each input and macro line.
-zl		Display the behaviour of the lexer.
-zp		Display changes to the purity status.
-zs		Display changes to the default parser scope.
-zt		Display each token passed between lexer and main parser.
-zu		Display changes to the composed entity and parser default utility.
-zx		Display full hex address of each object in diagnostics.
-zy		Display YACC parser progress.
-zz		Repeat certain failed invocations after generating an error to aid debug.

Predefined macros

__STDC__ with value 0

__cplusplus with value 0


File disposition

FOG can generate many output files some of which may collide with input files. Potential hazards are avoided by:

Beware that use of -f circumvents the latter two protections.

Declarations and corresponding files are not generated for

The default behaviour of FOG is to create a pair of files for each top-level class or namespace. This is appropriate for many classes, but can lead to a large number of include files for subsequent compilations. The number of files and placement within output files may be specified by the member declarations

    export/implementation entity;

to place the implementation of the current scope in the same file as the implementation file for entity, which may be an existing declaration of quoted file name.

    export/interface entity;

to place the interface of the current scope in the same file as the interface file for entity, which may be an existing declaration of quoted file name. An interface may also be placed with an implementation by

    export/interface entity/implementation;

FOG automatically determines declaration ordering, and generates include directives and appropraite guards as required. However FOG's analysis is fallible:

Assistance may be necessary to specify additional dependencies by adding member declarations

    using/interface entity;

to specify that the interface of the current scope uses the interface of entity, or

   using/implementation entity;

to specify that the implementation of the current scope uses the interface of entity, or

   int f(args) :{ using/implementation entity { body } };

to specify that the implementation of a function uses the interface of entity.