The Makefile, Project, and Workspace Creator (MPC)

The -relative Option.

• Some project types do not (completely) support the idea of accessing environment variables through the use of $() , and therefore MPC must ensure that generated projects are usable in these cases. In order to avoid the existence of $() variables within the generated project files, relative paths are put in place of those (where possible).
• The -relative option takes a single parameter of a name value pair, for example:

 

mwc.pl -relative PROJ_TOP=/usr/projects/top

 

• In above example, if the text "$(PROJ_TOP) " is found as a value for any mpb, mpc, mpd, or mpt variable then it is replaced by a path that is relative to /usr/projects/top . For example, if an mpc file located under /usr/projects/top/dir contained the following:

 

project {

includes += $(PROJ_TOP)

}

 

• The generated project file would contain text similar to:

 

CPPFLAGS += -I..

 

• The $(PROJ_TOP) string was replaced with a directory value that is relative to the directory in which the mpc file is located.

The -ti Option.

• The -ti option allows you to identify different template input files based on the type of target being built. Template input files correspond to four different categories: dll , lib , dll_exe , and lib_exe . Not all project types distinguish between the different categories, but the templates for various project types will be combined with different template input files, depending on the build target type, to generate different output.
• To override the default template input file names, a -ti option is provided. The -ti option takes a single parameter of the form type:file . The type is one of the four categories stated above and the file is the base name of an mpt file located somewhere in the include search paths.
• The following example shows a usage of the -ti option. It says that when generating a static project (lib), use the vc7lib template input file and when generating a dynamic project (dll), use the vc7dll template input file:

 

mpc.pl -type vc71 -ti lib:vc7dsplib -ti dll:vc7dspdll

 

• These happen to be the default values for the vc71 type, but it illustrates that a different template input can be specified for each category.

The -value_project Option.

• The -value_project option can be useful when the need arises to modify the value of an MPC variable across one or more mpc files. For example, if you wanted to generate all of your projects with an additional include search path you would run the following command:

 

mwc.pl -value_project includes+=/include/path

 

• In the above example, an additional include search path of /include/path would be placed in all generated projects.

The -value_template Option.

• This option modifies existing or adds new template input name/value pairs. For example, if you wanted to generate dynamic vc71 projects with only Release targets, you would run the following command:

 

mwc.pl -type vc71 -value_template configurations=Release

 

• To find out what template input variables are defined, see the individual mpd file of interest ( $ACE_ROOT/bin/MakeProjectCreator/templates/*.mpd and $MPC_ROOT/templates/*.mpd ) and search for names used within <% and %> . Names that are not listed as project keywords (See Assignment Keywords) are template variables.

Project Declarations

• Project declarations are similar to workspace declarations, but are a bit more complex. An mpc file can contain one or more "projects" and each project can inherit from base projects.

 

project(optional name): base_project, another_base_project {

exename = client

includes += directory_name other_directory

libpaths += /usr/X11R6/lib

 

Header_Files {

file1.h

file2.h

fileN.h

}

 

Source_Files {

file1.cpp

file2.cpp

fileN.cpp

}

}

 

• If the optional project name is not given, then the project name is taken from the name of the mpc file without the extension. Therefore, if your mpc file is going to contain multiple projects, it is important to provide project names to prevent each generated project from overwriting the other. MPC will issue an error and stop if duplicate project names are detected.

Base Projects

• Base projects can be of the extension mpb and mpc . If a file with the name of the base project with an mpb or mpc extension cannot be found within the mpc include search path, a fatal error is issued and processing halts.

Assignment Keywords

• See Assignment Keywords shows the keywords that can be used in an assignment (i.e. = , += or -= ) within an mpc file. The most commonly used keywords are shown in bold face.

Assignment Keywords

Keyword	Description
after	Specifies that this project must be built after 1 or more project names listed.
avoids	Specifies which features should be disabled in order to generate the project file. Under the GNUACE type, it also specifies which make macros should not be set to build the target.
custom_only	This setting instructs MPC to create projects that only contain custom generation targets. Any files included in the projects will be provided by custom component lists defined through the use of Define_Custom .
dynamicflags	Specifies preprocessor flags passed to the compiler when building a dynamic library.
dllout	If defined, specifies where the dynamic libraries will be placed. This overrides libout in the dynamic case.
exename	Determines that the project will be an executable and the name of the executable target.
includes	Specifies one or more directories to supply to the compiler for use as include search paths.
install	Specifies where executables will be installed.
libout	Specifies where the dynamic and static libraries will be placed.
libpaths	Specifies one or more directories to supply to the compiler for use as library search paths.
libs	Specifies one or more libraries to link into the target. Library modifiers may be added when being processed in the template file. For example, library modifiers are added when using the vc6 project type.
lit_libs	This is the same as libs except that a library modifier will not be added.
macros	Values supplied here will be passed directly to the compiler as command line defined macros.
pch_header	The name of the precompiled header file. See the discussion below this table for more information.
pch_source	The name of the precompiled source file. See the discussion below this table for more information.
pure_libs	This is similar to lit_libs except that no prefix or extension is added to the names specified.
postbuild	If this is defined in the project, the value will be interpreted as commands to run after the project has been successfully built. The <% %> construct (See Template Files (mpd)) can be used within this value to access template variables and functions of the template parser.
recurse	If set to 1, MPC will recurse into directories listed under component listings (such as Source_Files, Header_Files, etc.) and add any component corresponding files to the list. This keyword can be used as a global project setting or a component scoped setting.
requires	Specifies which features should be enabled in order to generate the project file. Under the GNUACE type, it also specifies which make macros should be set to build the target.
sharedname	Determines that the project will be a library and the name of the dynamic library target. See the discussion below this table for more information.
staticflags	Specifies preprocessor flags passed to the compiler when building a static library.
staticname	Determines that the project will be a library and the name of the static library target.
tagchecks	For GNUACE Make only, specifies one or more names to search for in the macros specified by tagname.
tagname	Specifies the GNUACE Make macro to check before building the target.
version	Specifies the version number for the library or executable.

• Assignments can also use the += and -= operators to add and subtract values from keyword values.
• If a sharedname is specified in the mpc file and staticname is not used, then staticname is assumed to be the same as sharedname . This also applies in the opposite direction.
• If neither exename, sharedname nor staticname is specified, MPC will search the source files for a main function. If a main is found, the exename will be set to the name of the file, minus the extension, that contained the main function. Otherwise, sharedname and staticname will be set to the project name.
• If the project name, exename, sharedname or staticname contain an asterisk it instructs MPC to dynamically determine a portion of the name based on certain defaults. If the project name contains an asterisk, then the asterisk will be replaced with the default project name. If exename, sharedname or staticname contains an asterisk, then the asterisk will be replaced with the project name.
• If the pch_header keyword is not used and a file exists, in the directory in which the mpc file is located, that matches *_pch.h it is assumed to be the precompiled header for that directory. If there are multiple pch files in the directory, then the precompiled header that closely matches the project name will be chosen. Similar logic applies for the pch_source keyword.

Components

• An mpc file can also specify the files to be included in the generated "project" file. These files are specified using the component names shown in See Component Names and Default Values. However, most of the time users will want to allow MPC to provide the default values for project files.

Component Names and Default Values

Name	Default Value
Source_Files	Defaults to all files in the directory that have the following extensions: cpp , cxx , cc , c , and C .
Header_Files	Defaults to all files in the directory that have the following extensions: h , hpp, hxx , and hh .
Inline_Files	Defaults to all files in the directory that have the following extensions: i and inl .
Template_Files	Defaults to all files in the directory that end in the following: _T.cpp , _T.cxx , _T.cc , _T.c , and _T.C .
Documentation_Files	Defaults to all files in the directory that match the following: README , readme , .doc , .html and .txt .
Resource_Files	Defaults to all files in the directory that match the project name and have an rc extension.

• If a component is not specified in the mpc file, the default value will be used. To disallow a particular set of files that may exist in the directory, you must declare an empty set of the particular component type.
• Each component name accepts two forms. The first form is a simple list of files within the construct.

 

Source_Files {

file1.cpp

file2.cpp

}

 

• The second form is a complex list of files within named blocks.

 

Source_Files(MACRO_NAME) {

BlockA {

file1.cpp

file2.cpp

}

BlockB {

file3.cpp

file4.cpp

}

}

 

• The second form allows the user to logically group the files to make future maintenance easier. Using this form has the effect of visually grouping files in the generated project file for the em3 , gnuace , vc6 , vc7 , vc71 and vc8 project types.
• If a file is listed in the Source_Files component list and a corresponding header or inline file exists in the directory, it is added to the corresponding component list unless it is already listed.

Verbatim Clause

• The verbatim construct can be used to place text into a generated project file verbatim. The verbatim syntax is as follows:

 

verbatim(<project type>, <location>) {

..

}

 

• When MPC is generating a project of type <project type> and encounters a marker in the template file (see See Template File Keywords) that matches the <location> name, it will place the text found inside the construct directly into the generated project. If the text inside the construct requires that white space be preserved, each line must be enclosed in double quotes. The following verbatim example would result in gnuace generated projects having a rule at the bottom of the GNUmakefile where the all: target depends on foo .

 

verbatim(gnuace, bottom) {

all: foo

}

 

Specific Clause

• The specific keyword can be used to define assignments that are specific to a particular project type. This will allow platform or OS-specific values to be placed into a project. For example, on one platform you may want to link in a library named qt-mt , but on another you need to link in qt-mt230nc .

 

specific(bmake, nmake, vc6, vc7, vc71, vc8) {

lit_libs += qt-mt230nc

} else {

lit_libs += qt-mt

}

 

• If an else clause is provided, it is required to be on the same line as the closing curly brace. You may also negate the project type (using '!') which will cause the specific to be evaluated for all types except the type specified.
• If a keyword used within a specific section is not recognized as a valid MPC keyword, it is interpreted to be template value modifier. In this situation, this construct works exactly the same way as the -value_template command line option (see See Command Line Options).

Conditional Clause

• This scope allows addition of source files conditionally based on a particular project type. The syntax is as follows:

 

conditional(<project type> [, <project type> ...]) {

source1.cpp

...

}

 

conditional(<project type> [, <project type> ...]) {

source1.cpp

...

} else {

source2.cpp

...

}

 

• If the else is provided, it is required to be on the same line as the closing curly brace. You may also negate the project type (using '!') which will cause the conditional to be evaluated for all types except the type specified.

Custom Types and Build Rules

• MPC allows you to define your own custom file types to support a variety of custom build rules. Below is an example of a custom definition.

 

project {

Define_Custom(MOC) {

automatic = 0

command = $(QTDIR)/bin/moc

output_option = -o

inputext = .h

pre_extension = _moc

source_outputext = .cpp

keyword mocflags = commandflags

}

 

// Custom Component

MOC_Files {

QtReactor.h

}

 

Source_Files {

QtReactor_moc.cpp

}

}

 

• The above example defines a custom file type, " MOC ", that describes basic information about how to process the input files and what output files are created. Once the custom file type is defined, MOC_Files can be used to specify the input files for this new file type.
• See Define_Custom Keywords contains the keywords that can be used within the scope of Define_Custom .

Define_Custom Keywords

Keyword	Description
automatic	If set to 1, then attempt to automatically determine which files belong to the set of input files for the custom type. If set to 0, then no files are automatically added to the input files. If omitted, then automatic is assumed to be 1. Custom file types that are automatic will have the side effect of possibly adding files to Source_Files , Inline_Files , Header_Files , Template_Files , Resource_Files and Documentation_Files depending on which extension types the command generates.
command	The name of the command that should be used to process the input files for the custom type.
commandflags	Any options that should be passed to the command.
dependent	If this is given a value, then a dependency upon that value will be placed upon all of the generated files. The default for this is unset and no dependency will be generated.
inputext	This is a comma separated list of input file extensions that belong to the command.
keyword <name>	This is a special assignment that allows the user to map <name> into the project level namespace. The value (if any) that is assigned to this construct must be one of the keywords that can be used within a Define_Custom clause. The result of this assignment is the ability modify the value of keywords that are normally only accessible within the scope of a custom component (e.g. command , commandflags , etc.).
libpath	If the command requires a library that is not in the normal library search path, this keyword can be used to ensure that the command is able to find the library that it needs to run.
output_option	If the command takes an option to specify a single file output name, then set it here. Otherwise, this should be omitted.
pch_postrule	If this is set to 1, then a rule will be added to the custom rule that will modify the source output files to include the precompiled header file.
postcommand	This allows users to create arbitrary commands that will be run after the main command is run to process the custom input files.
pre_extension	If the command produces multiple files of the same extension, this comma separated list can be used to specify them. For example, tao_idl creates two types of files per extension ( C.h , S.h , C.cpp , S.cpp , etc.) This applies to all extension types.
source_pre_extension	This is the same as pre_extension except that it only applies to source_outputext.
inline_pre_extension	This is the same as pre_extension except that it only applies to inline_outputext.
header_pre_extension	This is the same as pre_extension except that it only applies to header_outputext.
template_pre_extension	This is the same as pre_extension except that it only applies to template_outputext.
resource_pre_extension	This is the same as pre_extension except that it only applies to resource_outputext.
documentation_pre_extension	This is the same as pre_extension except that it only applies to documentation_outputext.
pre_filename	The syntax for this is the same as pre_extension , but the values specified are prepended to the file name instead of the extension. This applies to all extension types.
source_pre_filename	This is the same as pre_filename except that it only applies to source_outputext.
inline_pre_filename	This is the same as pre_filename except that it only applies to inline_outputext.
header_pre_filename	This is the same as pre_filename except that it only applies to header_outputext.
template_pre_filename	This is the same as pre_filename except that it only applies to template_outputext.
resource_pre_filename	This is the same as pre_filename except that it only applies to resource_outputext.
documentation_pre_filename	This is the same as pre_filename except that it only applies to documentation_outputext.
source_outputext	This is a comma separated list of possible source file output extensions. If the command does not produce source files, then this can be omitted.
inline_outputext	This is a comma separated list of possible inline file output extensions. If the command does not produce inline files, then this can be omitted.
header_outputext	This is a comma separated list of possible header file output extensions. If the command does not produce header files, then this can be omitted.
template_outputext	This is a comma separated list of possible template file output extensions. If the command does not produce template files, then this can be omitted.
resource_outputext	This is a comma separated list of possible resource file output extensions. If the command does not produce resource files, then this can be omitted.
documentation_outputext	This is a comma separated list of possible documentation file output extensions. If the command does not produce documentation files, then this can be omitted.
generic_outputext	If the command does not generate any of the other output types listed above, then the extensions should be listed under this.

• There is a special interaction between custom components and the source, header and inline components. If a custom definition is set to be "automatic" and custom component files are present but not specified, the default custom generated names are added to the source, header and inline component lists unless those names are already listed (or partially listed) in those component lists. See See Custom Types and Build Rules for more information about defining your own custom type.
• Particular output extensions for custom build types are not required. However, at least one output extension type is required for MPC to generate a target. Your command does not necessarily have to generate output, but an extension type is required if you want the input file to be processed during the project compilation.
• If the custom output can not be represented with the above output extension keywords (*_outputext) and you have knowledge of the output files a priori , you can represent them with the '>>' construct.
• Below is an example that demonstrates the use of '>>'. The command takes an input file name of foo.prp and produces two files that have completely unrelated filenames, hello.h and hello.cpp .

project {

Define_Custom(Quogen) {

automatic = 0

command = perl quogen.pl

commandflags = --debuglevel=1 --language=c++ \

--kernel_language=c++

inputext = .prp

keyword quogenflags = commandflags

}

 

Quogen_Files {

foo.prp >> hello.h hello.cpp

}

 

Source_Files {

hello.cpp

}

}

 

• You can use the '<<' construct to represent dependencies for specific custom input file. For instance, in the above example, assume that foo.prp depends upon foo.in, we would represent this by adding << foo.in as shown below.

Quogen_Files {

foo.prp >> hello.h hello.cpp << foo.in

}

 

• An additional construct can be used within the scope of a Define_Custom . This construct is called optional , and can be used to represent optional custom command output that is dependent upon particular command line parameters passed to the custom command.

project {

Define_Custom(TEST) {

optional(keyword) {

flag_keyword(option) += value [, value]

}

}

}

• In the above fragment, keyword can be any of the pre_extension , pre_filename keywords or any of the keywords that end in _outputext . The flag_keyword can be any of the custom definition keywords, however only commandflags has any functional value. The flag_keyword value is searched for the option value contained inside the parenthesis. If it is found the value or values after the += are added to the list specified by keyword . This can also be negated by prefixing the option with an exclamation point (!).
• The example below shows how the optional construct is used by the custom definition for the tao_idl command (see ACE_wrappers/bin/MakeProjectCreator/config/taoidldefaults.mpb ). The -GA option causes tao_idl to generate an additional source file (based on the idl file name) with an A.cpp extension. The -Sc option causes tao_idl to suppress the generation of S_T related files.

 

Define_Custom(IDL) {

...

inputext = .idl

source_pre_extension = C, S

header_pre_extension = C, S

inline_pre_extension = C, S

source_outputext = .cpp, .cxx, .cc, .C

header_outputext = .h, .hpp, .hxx, .hh

inline_outputext = .inl, .i

keyword idlflags = commandflags

 

optional(source_pre_extension) {

commandflags(-GA) += A

}

optional(template_outputext) {

commandflags(!-Sc) += S_T.cpp, S_T.cxx, S_T.cc, S_T.C

}

optional(header_pre_extension) {

commandflags(!-Sc) += S_T

}

optional(inline_pre_extension) {

commandflags(!-Sc) += S_T

}

}

 

• For custom file types, there are a few keywords that can be used within the custom file type component lists: command , commandflags , dependent , gendir , postcommand , and recurse .
• The recurse keyword works as described in See Assignment Keywords.
• The command , commandflags , dependent and postcommand keywords can be used to augment or override the value defined in the Define_Custom section.
• The gendir keyword can be used (only if output_option is set in Define_Custom ) to specify the directory in which the generated output will go. Here is an example:

 

MOC_Files {

commandflags += -nw

gendir = moc_generated

QtReactor.h

}

 

Source_Files {

moc_generated/QtReactor_moc.cpp

}

 

• In the above example, the -nw option is added to commandflags and the generated file ( QtReactor_moc.cpp ) is placed in the moc_generated directory. If the MOC custom definition did not have an output_option setting, then options would need to be added to commandflags or a postcommand would need to be defined to ensure that the output actually went into the moc_generated directory.