C+=2 Compilation units (ie, source code and source documenation files) are collected together with one Project File. This textual file provides a powerful alternative to a makefile, and can integrate with one or more makefiles if required.
A C+=2 project file (suffix ".c2p") is a simple text file which states which files are part of the project, typically by stating directories. The name of the project file is the name of the executable or library produced.
A simple project file simply lists the files needed in a program, using wild cards of * for any file in the directory, or ** for any file in that directory or subdirectories. The simplest contains only a single character, *; indeed this is common for small programs.
eg, show.c2p
*
This is a project file for a program called show, where all .c2 files in the directory are to be built into an executable.
The compiler is responsible for evaluating which files have changed since the previous compile, if any (typically by using a timestamp, any change earlier or later will count as a change), and rescanning only those changed for global names and dependencies. It will also recompile all compilation units which are dependant on that file, even if they have not changed.
This multistage process is simple, fast, and not prone to errors like a traditional makefile, where dependancies often need to be hand coded or kept up to date using other tools; makefiles are also not ideally suited to the multistage build.
For many projects, makefiles are essential part of existing software and it is necessary to integrate the two.
Integration is possible with the "makefile on top" or the "project file on top".
A makefile can call a C+=2 compiler to compile code specified by a subsidiary project file. Typically this subsidiary project file emits a library file (use "[build] lib" in the project file) which can then be linked by the makefile with other parts of the project, possbily written in different languages.
result.lib: c2
A Project File can make a subsidiary makefile, typically this builds object files or a library file into directories which the project file takes and links. Makefile lines can be added using the [makefile] section or else a whole makefile can be executed by calling make from such a section.
If it is desired to include a header file from a C or C++ project into a C+=2 build, where the code is supplied seperately as either object, library or even .c or .cpp file to be compiled, then either #include all the relevant headers manually, or use the [provides] section to specify it.
Remember to specify the body code which implements those function in the link by placing the object in a [makefile] section or the library the [files] section.
Non C/C++ functions can be treated in the same way by writing appropriate function prototypes either directly in a .c2 file or elsewhere and including it.
Apart from this purpose, the use of #include in C+=2 is discouraged.
Sections in project files are delimited by names in square brackets. Comments need a prefix of # in a project file, since // is potentially a file name or valid text in a comment template.
The files section has optional introducer [files].
A list of the files needed in a program, using wild cards of * for any file in the directory, or ** for any file in that directory or subdirectories goes here.
Names are relative to the project file directory unless they are in absolute format (with a leading / or similar local convention).
eg,
* common/* src/**
Specifies which file types are to be compiled, and by what.
Files with .c2 .cpp .c and local conventions for object and library (.obj .o .lib .a .so) are compiled and linked automatically.
Documentation files, suffix .c2d .c2rtf .c2html are also processed.
Other types can be listed here in the format file action.
Either a full file name or a suffix may be specified for file. action consists of a tool name and optional parameters. The symbol $< in the action section will be replaced by the name of the file. When the tool is executed, the current directory is set to the one containing the file.
eg,
[types] .feg feg $< makefile make
The output from a tool is typically one or more files which can be processed automatically, such as .c2 .c or object files, in a directory specifed in [files]. These are then processed as normal. An appropriate line in the [after] can tidy up and remove these temporary files if desired.
This specifies build specific information.
Target type appears in the build section:
exe builds an executable (default). lib builds a library or archive file. dll builds a dll or shared object file. obj builds to object files.
In the first 3 cases the name used is that of the project file, with OS specific suffix where appropriate. In the final case the names are those of the source files.
Specify more than one if needed.
Note that the compiler may split source compilation units into smaller units for linking into an exe or lib file, to permit finer granularity and thus smaller executables when not all functions of a class are used, for example. This should be transparent to the user. If object files are output, then exactly one object file per source file is generated, and any benefit of finer granularity is lost.
You can also specify the documentation build with this section:
html builds html documentation (default) txt builds text documentation
Specify more than one if needed.
For more information, see Testing
System specific information may appear in a [target] section; there may be multiple [target] sections for different targets and those not appropriate will be ignored.
eg:
[target win32] [target dos] [target linux] [target mac] [target epoc] [target elate]
More detail of these is given elsewhere, in OS specific documentation with the compiler. The format is sometimes rather specific, eg, the [target win32] section has a windows-specific ".def" information in it, and the [target epoc] section has the EPOC specific build information.
Like the other sections, it is possible to omit this section, and default information will be used. Since no error message will be generated on an unknown target, a spelling error can cause the section to be ignored - do check carefully!
This introduces a comment template for functions. Place the items to be put in the comment to each function in here, with special symbols:
%funcname% name of function %argname% name of argument (this line repeated for each) %funcdec% declaration of function %argdec% declaration of argument (repeated for each) %return% return documentation line (repeated zero or once) %blank% blank line %text% user text
eg, a block which preceeds the function:
[comment] ////////////////////////////////////////// // %funcname% ////////////////////////////////////////// // %text% // %argname% : %text% // Returns : %return%%text% //////////////////////////////////////////
eg, a comment which occurs on the function itself
[comment] ////////////////////////////////////////// %blank% %funcdec% // %text% %argdec% // %text%
As [comment] but for files. Use %filename% for the name of file.
While the compiler is rewriting comments, it may as well tidy up code formatting. Since numerous styles exist, this optional feature is useful to bring code into a consistent and readable style.
Like the comments, it will only rewrite the file if it detects it is not right, and then only if it is writable.
Keywords valid in this section are:
off - default, no rewriting
tab - indent using tab
3 spaces - indent using 3 spaces (any number can be specified)
braces-indented - EPOC style
brace-at-eol - if (a) {
brace-at-sol - { code();
classmember-indent - indent class members (default no indent)
namspacemember-indent - indent namespace members (default no indent)
Specifies actions to perform before the build. This runs a shell script on your local OS, and therefore may not be portable.
Typical uses for before are ensuring a tool used in [types] is up to date, checking out sources from a revision control system, or performing preprocessor actions.
These actions will always be executed first, and failure will not stop the build.
Specifies actions to perform after the build. This runs a shell script on your local OS, and therefore may not be portable.
Typically this is used to "publish" the built code or documentation; to copy it to a working directory.
It will NOT be executed if the build fails.
Includes another file in a project file.
eg,
[include] /other/ping.c2p
For system use only when setting up libraries: manually coded .c2x file follows. No other project actions are taken.
NB: obsolescent; see also [provides]
For listing C or C++ header files and what they provide:
header.h F items provided by header F more items otherhead.h F other
The Full format of "header" line is:
[define=value ][namespace::][<]headername[>][ -llib]
Most of these "special" fields are used only for defining libraries.
Lines to add to a makefile for C or C++ or other languages to be build separately but linked with the C+=2 code. Any .o or .obj targets are automatically added to the link.
eg:
file.o: file.cpp file.h other.h wow.o: wow.f77 f77-compiler wow.f77