The Makefile, Project, and Workspace Creator (MPC)

Additional Option Descriptions

• Some of the options in Command Line Options require an expanded explanation. You will find more information on the -relative, -ti, -value_project and -value_template options below.

Project Files (mpc)

• Project files, those with the mpc extension, contain such things as include paths, library paths, source files and inter-project dependencies. An mpc file can contain one or more “projects” each of which needs to be uniquely named to avoid project generation errors. Projects represent build targets such as libraries and executables.

Workspace Files (mwc)

• Workspaces are defined by providing a list of mpc files, directories or other mwc files in a single mwc file. For each mpc file, the Workspace Creator calls upon the Project Creator to generate the project. After all of the projects are successfully generated, the tool-specific workspace is generated containing the projects and any defined inter-project dependency information (if supported by the build tool). An mwc file can contain one or more “workspaces,” each of which needs to be uniquely named. If no workspace files are provided to the workspace creator, the current directory is traversed and any mpc files located will be part of the workspace that is generated.

Base Project Files (mpb)

• One of the many unique and useful features of MPC is that the project definition files can use inheritance. Project inheritance allows a user to set up a base project (mpb file) that can contain information that is applicable to all derived projects. Common project attributes, such as include paths, library paths, and inter-project dependencies, could be described in this base project and any project that inherits from it would contain this information as well.

Base Workspace Files (mwb)

• As with projects, workspaces can also inherit from other workspaces. A base workspace can provide workspace information that may be common to other workspaces.

mwc and mwb

• Workspaces can contain individual mpc files or directories. There can be one or more workspaces defined within a single mwc file.

•  

  workspace(optional name): optional_base_workspace {

    file.mpc

    directory

    other.mwc

   

    exclude(vc6, vc7, vc71, vc8, vc9, vc10, nmake) {

      this_directory

    }

   

    exclude(prop:microsoft) {

      non_microsoft

    }

   

    specific(rpmspec) {

      rpm_version = 1.0

    }

  }

   

• A workspace can be given a name. This is the value given in the parentheses after the keyword workspace. If the workspace is not given a name, the workspace name is taken from the name of the mwc file without the extension.
• Workspaces can also inherit from other workspaces. In the above example, optional_base_workspace would be the base name of an mwb file with no extension that contains workspace information. This information would then be included in each workspace that inherits from it.
• The lines between the curly braces contain assignments, mpc files, directories, other workspace files or exclusion sections. For each listed item,
  • an mpc file will be included in the workspace
  • a directory recursively traversed and any mpc files found will be included
  • a workspace file will be aggregated into the main workspace.
• A workspace can have assignments interspersed within the directories and mpc files. These assignments modify the way projects are generated.
• The cmdline setting can be used to provide command line options that would normally be passed to mwc.pl (see Command Line Options). However, the -type, -recurse , -noreldefs , -make_coexistence, -genins, -into and -language options as well as input files are ignored. Environment variables may be accessed through $NAME, where NAME is the environment variable name. The cmdline assignment may be useful for workspaces that require specific mwc.pl options in order to process correctly.
• The only other setting supported by mwc.pl is implicit. If implicit is set to 1 then default project files are generated in each directory where no mpc file exists. The implicit keyword can also be set to the name of a base project. In this case, the implicitly generated project will inherit from the base project specified in the assignment. Either way, if the directory does not contain files that can be used within a project, no project is created. Setting implicit can be useful when you want to define specific workspaces, but the MPC defaults are sufficient for the directories involved within the workspace.
• Workspaces support a specific clause conceptually and syntactically similar to the project specific clause. Any variables assigned within the clause are only available to workspaces, not to projects. Two sorts of assignments are possible: first are assignments to the keywords cmdline and implicit and the second are type-specific variables. Consult the documentation for the type for details on type-specific variables. Keyword assignments impact the entire workspace, not just the specific scope.
• Scoped assignments are assignments that are associated with specific mpc files or directories listed with the scope of the assignment. The following example shows a scoped assignment of cmdline that only applies to one of the mpc files listed in the workspace. In this example, directory/foo.mpc would be processed as if the -static option had been passed on the command line whereas other directories and mpc files would not.

•  

  workspace {

    ...

    static {

      cmdline += -static

      directory/foo.mpc

    }

   

    exclude(gnuace, make) {

      some.mpc

    }

   

    // Associate the name "other" with dir3

    associate(other) {

      dir3

    }

  }

   

• Exclusion sections are used to prevent directories and mpc files from being processed. These excluded directories and mpc files will be skipped when generating project files and workspaces. The exclude keyword accepts project types as well as properties (see Properties) within the parentheses (as above), which will cause the workspace creator to only exclude the listing for particular types. If no types are provided, exclusion will take place for all project types.
• The associate scope associates a name with one or more directories. This does not add directories to a workspace, it only makes an association. This may or may not have an effect on the generated workspace; it depends solely upon whether the project type supports associations. Currently automake is the only project type that supports associations. Each directory listed under an association is grouped together and built conditionally based on the association name.
• Comments are similar to the C++ style comments. Any text after a double slash (// ) is considered a comment.

mpc and mpb

The Feature File

• The term feature, as used by MPC, describes different concepts or external software that a project may require in order to build properly. The feature file determines which features are enabled or disabled which has a direct effect on whether or not MPC generates a project.
• It supports the standard comment (// ) and assignment of numbers to feature names. These feature names will correspond to values given to the requires and avoids keywords in mpc files.
• If a feature is not listed in the feature file or is listed with a boolean value of true (1), that feature is enabled. If a feature is listed and has a boolean value of false (0), that feature is disabled.
• If a feature name is listed in the requires value for a particular project and that feature is enabled, that project will be generated. If the feature is not enabled, the project will not be generated.
• The opposite holds true for the avoids keyword. If a feature name is listed in the avoids value for a project and the feature is disabled, that project will be generated. If the feature is enabled, the project will not be generated.
• The global feature file for MPC contains the following values.

•  

  boost = 0

  bzip2 = 0

  java = 0

  mfc = 0

  python = 0

  qt = 0

  rpc = 0

  swig_java = 0

  swig_perl = 0

  swig_php = 0

  swig_python = 0

  swig_ruby = 0

  swig_tcl = 0

  uses_wchar = 0

  xalan = 0

  xerces = 0

  xerces2 = 0

  xerces3 = 0

  ziparchive = 0

  zlib = 0

  zzip = 0

   

• In the above contents, all of these features are disabled for each project generated. If these values do not suit your needs, then you must do one of the following:
• • Create a project specific feature file in the config directory (ex., make.features for the make project type) to set features for a particular project type.
  • Create a default.features file in the config directory that contains the feature set you need. These will be applied to all project types.
  • Create a feature file anywhere you like with the features you want and use the -feature_file option to specify the location.
  • Use the -features option to dynamically modify the feature settings.
• Generated projects will have a combination of features specified in the global.features file as well as in your feature file. Therefore, if a feature is disabled in the global file and you want to enable it, you must explicitly enable it in your feature file.

Feature Projects

• A feature project contains information as a project would, but can only be a base project and will only be added to a sub project if the features that it requires are enabled or the features that it avoids are disabled.
• A feature definition requires at least one feature name. A name by itself specifies that the feature must be enabled. A ’!’ in front of the feature name indicates that the feature must be disabled. There may be more than one comma separated feature listed between the parenthesis.
• The following example show how to declare a feature project.

•  

  // ziparchive.mpb

  feature(ziparchive) {

    includes += $(ZIPARCHIVEROOT)

    libpaths += $(ZIPARCHIVEROOT)/lib

    libs     += ziparch

  }

   

• With this example, any project that inherits from the ziparchive base feature project will contain the project information only if the ziparchive feature is enabled.

Source Files

• New source files are added and others are removed quite often in a developing project. If the Source_Files component is left out of an mpc file, then MPC will assume that any file matching one of the source extensions is to be included in the project. For most project types, the source extensions are: .cpp, .cxx, .cc, .c and .C. Only the following extensions are considered source extensions: .cpp, .cxx and .c for the em3 and vc6 project types as eMbedded Visual C++ and Visual C++ 6.0 do not understand files with the .cc or .C extension.

Template Files

• MPC assumes that any file matching one of the template extensions is to be included in the project if the Template_Files component is left out of an mpc file. For most project types, the template extensions are: _T.cpp, _T.cxx, _T.cc, _T.c, and _T.C. However, only the _T.cpp and _T.cxx extensions are considered template extensions for the em3 and vc6 project types.
• If the Source_Files component is defaulted, and a file is explicitly listed in the Template_Files section that happens to appear to MPC as a source file (i.e., has a source file extension, but does not have _T directly before it), MPC will automatically exclude it from the Source_Files component.

Inline Files

• As with source files, the Inline_Files component can be left out of an mpc file to allow it to generate defaults. Files that match the .i and .inl extensions are considered inline files.
• The Inline_Files component has a special interaction with the Source_Files component. If the Source_Files component has files listed and the Inline_Files component is omitted, then each source file is matched to an inline file. If the matching inline file is found or would be generated from a custom command, it is added to the Inline_Files component list.

Header Files

• As with source files, the Header_Files component can be left out of an mpc file to allow it to generate defaults. Files that match the .h, .hpp, .hxx, and .hh extensions are considered header files.
• The Header_Files component has a special interaction with the Source_Files component. If the Source_Files component has files listed and the Header_Files component is omitted, then each source file is matched to a header file. If the matching header file is found or would be generated from a custom command, then it is added to the Header_Files component list.

Documentation Files

• The Documentation_Files component, if omitted, will default to all files that end in the following: README, readme, .doc, .html and .txt.

Resource Files

• The Resource_Files component, if omitted, will default to only the files that end in .rc and are similar to the name of the project. For example, if a directory contains three .rc files and the project name is foo, only the .rc files that contain the word foo will automatically be added to the Resource_Files component list.

Custom Defined Files

• The Custom Defined Files components have a special interaction with the Source_Files component. If the custom command generates source files and has the automatic_out setting set to 1, they will automatically be added to the Source_Files component list. If any of the files listed in the Source_Files components list match any of the generated source file names, then none of the generated source file names will be automatically added to the Source_Files components list.

Example MPC File

• The example below uses the directory contents of $TAO_ROOT/orbsvcs/performance-tests/RTEvent/lib to illustrate the simplicity of mpc files:

•  

  Auto_Disconnect.cpp Loopback_Supplier.h RTEC_Initializer.cpp

  Auto_Disconnect.h Low_Priority_Setup.cpp RTEC_Initializer.h

  Auto_Disconnect.inl Low_Priority_Setup.h rtec_perf_export.h

  Auto_Functor.cpp Low_Priority_Setup.inl RTEC_Perf.mpc

  Auto_Functor.h Makefile RTPOA_Setup.cpp

  Auto_Functor.inl ORB_Holder.cpp RTPOA_Setup.h

  Client_Group.cpp ORB_Holder.h RTPOA_Setup.inl

  Client_Group.h ORB_Holder.inl RTServer_Setup.cpp

  Client_Group.inl ORB_Shutdown.cpp RTServer_Setup.h

  Client_Options.cpp ORB_Shutdown.h RTServer_Setup.inl

  Client_Options.h ORB_Shutdown.inl Send_Task.cpp

  Client_Pair.cpp ORB_Task_Activator.cpp Send_Task.h

  Client_Pair.h ORB_Task_Activator.h Send_Task_Stopper.cpp

  Client_Pair.inl ORB_Task_Activator.inl Send_Task_Stopper.h

  Consumer.cpp ORB_Task.cpp Send_Task_Stopper.inl

  Consumer.h ORB_Task.h Servant_var.cpp

  Control.cpp ORB_Task.inl Servant_var.h

  Control.h Peer_Base.cpp Servant_var.inl

  EC_Destroyer.cpp Peer_Base.h Shutdown.cpp

  EC_Destroyer.h PriorityBand_Setup.cpp Shutdown.h

  EC_Destroyer.inl PriorityBand_Setup.h Shutdown.inl

  Federated_Test.idl PriorityBand_Setup.inl Supplier.cpp

  Implicit_Deactivator.cpp RIR_Narrow.cpp Supplier.h

  Implicit_Deactivator.h RIR_Narrow.h SyncScope_Setup.cpp

  Implicit_Deactivator.inl RT_Class.cpp SyncScope_Setup.h

  Loopback_Consumer.cpp RT_Class.h SyncScope_Setup.inl

  Loopback_Consumer.h RT_Class.inl TAO_RTEC_Perf.dsp

  Loopback.cpp RTClient_Setup.cpp TAO_RTEC_Perf.dsw

  Loopback.h RTClient_Setup.h Task_Activator.cpp

  Loopback_Pair.cpp RTClient_Setup.inl Task_Activator.h

  Loopback_Pair.h RTCORBA_Setup.cpp Task_Activator.inl

  Loopback_Pair.inl RTCORBA_Setup.h

  Loopback_Supplier.cpp RTCORBA_Setup.inl

   

• The following mpc file (RTEC_Perf.mpc ) shows the simple and small number of lines required to generate usable build tool project files.

•  

  project(RTEC_Perf): strategies, rtcorbaevent, minimum_corba {

    sharedname = TAO_RTEC_Perf

    idlflags += -Wb,export_macro=TAO_RTEC_Perf_Export \

                -Wb,export_include=rtec_perf_export.h

    dllflags += TAO_RTEC_PERF_BUILD_DLL

   

    Template_Files {

      Auto_Disconnect.cpp

      Auto_Functor.cpp

      Low_Priority_Setup.cpp

      RIR_Narrow.cpp

      Servant_var.cpp

      Shutdown.cpp

      Task_Activator.cpp

    }

  }

   

• A line-by-line explanation of the example mpc file is listed below.

•  

  project(RTEC_Perf): strategies, rtcorbaevent, minimum_corba {

   

• The first line declares a project named RTEC_Perf that inherits from the base projects listed after the colon.

•  

  sharedname = TAO_RTEC_Perf

   

• Line two determines that the project is a library and the library name is TAO_RTEC_Perf.

•  

  idlflags += -Wb,export_macro=TAO_RTEC_Perf_Export \

  -Wb,export_include=rtec_perf_export.h

   

• Lines three and four add to the flags passed to the IDL compiler when processing the idl files.

•  

  dllflags += TAO_RTEC_PERF_BUILD_DLL

   

• Line five adds TAO_RTEC_PERF_BUILD_DLL to the dllflags, which defines a macro that is used by the rtec_perf_export.h header file.

•  

  Template_Files {

    Auto_Disconnect.cpp

    Auto_Functor.cpp

    Low_Priority_Setup.cpp

    RIR_Narrow.cpp

    Servant_var.cpp

    Shutdown.cpp

    Task_Activator.cpp

  }

   

• Lines 7 through 15 name the listed cpp files as part of the Template_Files.
• You may have noticed that there isn’t much to the file above. With the default behaviors that are built into MPC, there does not need to be. We rely on the defaults to determine the values of IDL_Files, Source_Files, Inline_Files , and Header_Files. Since the template files do not match the MPC built-in defaults, we must explicitly list them. We also rely on inheritance to get many of the TAO-related options.

Template Files (mpd)

• Template files make up the bulk of what MPC puts into each generated project file. They provide the plain text and the layout of the data provided by the mpc files, using various template directives.
• Template directives are declared using a <% %> construct. This construct is used to create if statements, for loops and to access variables. One thing to note is that any text, including white space, that is not enclosed within <% %> is left untouched and is passed directly into the generated project file.
• An if statement can appear on a single line or it can span multiple lines. For example, the following line:

•  

  <%if(exename)%>BIN = <%exename%><%else%>LIB = <%sharedname%><%endif%>

   

• is equivalent to:

•  

  <%if(exename)%>

  BIN = <%exename%>

  <%else%>

  LIB = <%sharedname%>

  <%endif%>

   

• A foreach statement can also appear on a single line or can span multiple lines. As described below in the keywords section, the foreach statement evaluates the variable in a space-separated list context.
• There are a couple of ways to write a foreach loop. The first and preferred way is to name the loop variable and then list each variable to be evaluated.

•  

  FILES=<%foreach(fvar, idl_files source_files header_files)%> <%fvar%><%endfor%>

   

• The second way is to let the foreach statement determine the loop variable. With this style, each value can be accessed via the first variable name passed to the foreach with the trailing ’s ’ removed.

•  

  FILES=<%foreach(idl_files source_files header_files)%> <%idl_file%><%endfor%>

   

• Note that the <%idl_file%> variable will contain each individual value of the idl_files, source_files and header_files list. If the variable in the foreach does not end in ’s ’, the variable of the same name within the foreach will contain each individual value, e.g.,

•  

  <%foreach(filelist)%> <%filelist%><%endfor%>

   

• The following table lists keywords that can appear in template files.

• Template File Keywords

  Keyword	Description
  basename	Evaluates the variable name and removes the directory portion from that value.
  basenoextension	This is similar to basename except that the extension is also removed from the variable name value.
  comment	The value passed to comment is ignored and can be any set of characters, except a new line or a closing parenthesis.
  compares	This function returns true if the variable value (first parameter) is equal to the string value (second parameter).
  contains	This function returns true if the variable value (first parameter) contains the regular expression (second parameter).
  deref	Dereference the variable passed as a parameter, treating its value as another variable name and returning that variable's value.
  dirname	Evaluates the variable name and removes the basename from that value.
  duplicate_index	This function returns a number based on the number of times a file with the same name (but different directory) is seen within a project. The function returns false upon the first occurrence of a file.
  else	Used with the if statement. An else block will be evaluated if the statement does not evaluate to true.
  endfor	Used with foreach. This ends foreach block.
  endif	Used with the if statement. This ends an if or if/else block.
  ends_with	This function returns true if the variable value (first parameter) ends with the regular expression (second parameter).
  eval	This is similar to eval in perl. The template variable passed to this function will be evaluated within the context of the current template.
  extensions	Returns a list of extensions based on the component name parameter (e.g., source_files, header_files, etc.)
  flag_overrides	This is directly related to overriding the project-wide settings in an mpc file. It takes two variable names that are comma separated. The first corresponds to a file name and the second is any variable name.
  foreach	The given variable names are evaluated in a list context which is space separated.
  forfirst	Used with foreach. The literal value passed to forfirst will be placed on the first iteration of foreach.
  forlast	Used with foreach. The literal value passed to forlast will be placed on the last iteration of foreach.
  fornotfirst	Used with foreach. The literal value passed to fornotfirst will be placed on each iteration of foreach except for the first.
  fornotlast	Used with foreach. The literal value passed to fornotlast will be placed on each iteration of foreach except for the last.
  full_path	Returns full path of the value of the variable name passed a the parameter.
  has_extension	Returns true is the variable value has a file extension.
  if	Used to determine if a variable is defined. The not operator (! ) can be used to invert the if check. This construct will only check for values defined within an mpc or mpt file. Default values (even those implemented by the project creators) are not considered in the if statement.
  keyname_used	This function is used to associate a key with a variable value. If the key has been associated with a variable value more than once, either through physical repetition of the key in the template or through evaluation of a foreach context, the count of association will be appended to the output.
  lc	Return the given variable value in all lower case characters.
  marker	This is directly related to the verbatim keyword from the mpc syntax. This can be used to designate markers within a template. Ex. <%marker(local)%>.
  multiple	This function returns true if the array parameter contains multiple values.
  noextension	Evaluates the variable name value as a file name and removes the extension from that value including the period.
  normalize	Convert spaces, dashes, slashes, dollar signs, parenthesis and dots in the given variable value to underscores.
  remove_from	This function will remove a file in a component list. It requires three parameters. The first parameter is a component name (e.g., Source_Files), the second parameter is a regular expression pattern and the third parameter is a project or template variable name. The fourth and optional parameter allows you to alter the project or template variable value by removing the end matching portion. If the value of the project or template variable (i.e., parameter three) after being modified by parameter four and having the regular expression pattern (i.e., parameter two) appended to it matches any value within the compent list (named by parameter one), it will be removed from that component list and passed back. any
  reverse	This function reverses the order of the array parameter values.
  scope	This is used to set the scope of execution of a function that will operate on the template output. A scope is begun by passing "enter" as the first parameter and a function name as the second parameter. Currently, the only function name supported is "escape". The third parameter specifies a string on which the function will operate. Any template text that matches the string parameter while within this scope will be transformed by the function parameter. A scope is then ended by passing "leave".
  set	This function is used to set or create a template variable. This function takes two parameters; the first is the template variable name and the second is the variable value.
  sort	This function sorts the array parameter values.
  starts_with	This function returns true if the variable value (first parameter) starts with the regular expression (second parameter).
  transdir	Replaces values within the directory portion of a variable value with something that can be used as a relative path. The current working directory is removed and ".." is replaced with "dotdot".
  translate_vars	The first parameter to this function is the name of a variable. The second, optional, parameter is the operating system for which the project is being generated (e.g., linux, solaris, win32, etc.) It replaces $(...) found within the value of the variable with the equivalent environment variable reference based on the operating system.
  uc	Return the given variable value in all upper case characters.
  ucw	Return the given variable value with the first letter of each word in upper case. Words are separated by spaces or underscores.
  uniq	This function returns the unique set of the array parameter values.

• The following table lists special names that can be used as variables in some template files. The variables listed in the Common Pseudo Variables table can be used as well (except for <%temporary%>).

• Special Values used in Template Files

  Value	Description
  am_version	Implemented by the Automake project creator module, converts the version setting into a suitable value for automake.
  ciao	Implemented by the GNUACE project creator module, specifies that the project uses CIAO.
  compilers	Implemented by the Make project creator module, provides the compiler name based on the current project language.
  cppdir	This value is implemented by the BMake project creator module. It returns a semicolon separated list of directories taken from each value in the Source_Files list.
  custom_types	Contains a list of the custom build types. See Custom Types for more details.
  cwd	The full current working directory.
  forcount	This only has a value within the context of a foreach and provides a 1 based count, by default, of the index of the elements in foreach.
  guid	This value is implemented by the VC7 and WIX project creator modules. It returns a guid value based on the project that is usable within VC7, VC71, VC8, VC9, VC10 and WIX project files.
  language	This value is implemented by the VC7 and Make project creator modules. It returns the current language setting for the project.
  make_file_name	This value is implemented by the VC6 and EM3 project creator modules. It returns the project name with the make file extension that corresponds to the particular project type.
  project_file	This variable contains the name of the output file for the current project being generated.
  project_name	This variable contains the name of the current project being generated.
  rcdir	This value is implemented by the BMake project creator module. It returns a semicolon separated list of directories taken from each value in the Resource_Files list.
  source_directory	This value is implemented by the WIX project creator module. It converts the variable portion of the binary output directory (either exeout, dllout, or libout) to a suitable value for WIX.
  tao	Implemented by the GNUACE project creator module, specifies that the project uses TAO.
  vcversion	This value is implemented by the VC7ProjectCreator. It returns the version number of the type of project being generated. 7.00 is return for vc7, 7.10 is return for vc71 and 8.00 is returned for vc8, 9.00 is returned for vc9, 10.00 is returned for vc10.
  vpath	This value is implemented by the GNUACEProjectCreator. It returns a value, based on the location of the source files, that specifies the VPATH setting for GNU Make.

• Template Variable Documentation

• Template variables used within the MPC templates are numerous and vary from template to template; there are far too many to include in this document. However, you can generate an HTML document containing all of the template variables used within a template using the document_template.pl script found in the devtools directory under the MPC root directory. You may find that some templates and individual template variables are well documented and, unfortunately, some are not.
• The script will generate documentation for an individual template file. The usage is as follows:

•  

  document_template.pl v1.3

  Usage: document_template.pl <template> [<html output> [language]]

   

  html output - This defaults to the name of the template file with the .mpd

                extension replaced with .html.

  language    - This defaults to the language for which the template is designed.

                It can be any of the valid language settings for MPC:

                cplusplus csharp java vb

Template Input Files (mpt)

• Template input files provide build tool specific information that is common to all projects, such as compiler switches, intermediate directories, compiler macros, etc. Each project type can provide template input files for dynamic libraries, static libraries, dynamic executables and static executables. However, none of these are actually required by MPC.
• The template input files are more free-form than the other MPC file types. It is similar to the mpc syntax except that there is no project definition and there is only one keyword. The keyword, conditional_include, is used to include other mpt files if they can be found in the MPC include search path. If the name listed in double quotes after conditional_include is not found, it is ignored and no warning is produced. The mpt extension is automatically added to the name provided.
• The template input files contain variable assignments and collections of variable assignments. A variable assignment is of the form:

•  

  variable_name = value1 "value 2"

  variable_name += another_value

   

• This variable can then be used within the corresponding mpd file.
• Variable assignments can be grouped together and named within the mpt file and used as scoped variables within the mpd file. The following example shows the use of collections of variable assignments.

•  

  // mpt file

  configurations = Release Debug

  common_defines = WIN32 _CONSOLE

   

  Release {

    compile_flags = /W3 /GX /O2 /MD /GR

    defines = NDEBUG

  }

   

  Debug {

    compile_flags = /W3 /Gm /GX /Zi /Od /MDd /GR /Gy

    defines = _DEBUG

  }

   

  conditional_include "vcfullmacros"

   

• Below is the portion of the mpd file that would use the information provided in the mpt file above.

•  

  <%foreach(configurations)%>

  Name = <%configuration%>

  <%compile_flags%><%foreach(defines common_defines)%> /D <%define%>=1<%endfor%>

   

  <%endfor%>

   

• The following output is generated from the above example:

•  

  Name = Release

  /W3 /GX /O2 /MD /GR /D NDEBUG=1 /D WIN32=1 /D _CONSOLE=1

   

  Name = Debug

  /W3 /Gm /GX /Zi /Od /MDd /GR /Gy /D _DEBUG=1 /D WIN32=1 /D _CONSOLE=1

   

• If a foreach variable value corresponds to a variable group name, that variable group is available within the scope of that foreach.
•  

Template

• The best thing to do is to start with the template. The template is the most important piece when adding a new project type. It basically tells MPC how to lay out all of the information it gathers while processing an mpc file. The template file will have a mixture of plain text and the mpd syntax described in the Template Files section. Here is our sample fictional.mpd.

• //=======================================================================

  // This project has been generated by MPC.

  // CAUTION! Hand edit only if you know what you are doing!

  //=======================================================================

   

  // Section 1 - PROJECT OPTIONS

  ctags:*

  debugSwitches:-nw

  //end-proj-opts

   

  // Section 2 - MAKEFILE

  Makefile.<%project_name%>

   

  // Section 3 - OPTIONS

  //end-options

   

  // Section 4 - TARGET FILE

  <%if(exename)%>

  <%exename%>

  <%else%>

  <%if(sharedname)%>

  <%sharedname%>

  <%else%>

  <%if(staticname)%>

  <%staticname%>

  <%endif%>

  <%endif%>

  <%endif%>

   

  // Section 5 - SOURCE FILES

  <%foreach(source_files)%>

  <%source_file%>

  <%endfor%>

  //end-srcfiles

   

  // Section 6 - INCLUDE DIRECTORIES

  <%foreach(includes)%>

  <%include%>

  <%endfor%>

  //end-include-dirs

   

  // Section 7 - LIBRARY DIRECTORIES

  <%foreach(libpaths)%>

  <%libpath%>

  <%endfor%>

  //end-library-dirs

   

  // Section 8 - DEFINITIONS

  <%foreach(macros defines)%>

  -D<%macro%>

  <%endfor%>

  <%if(pch_header)%>

  <%foreach(pch_defines)%>

  -D<%pch_define%>

  <%endfor%>

  <%endif%>

  //end-defs

   

  // Section 9 - C FLAGS

  <%cflags("-g")%>

   

  // Section 10 - LIBRARY FLAGS

  <%libflags%>

   

  // Section 11 - SRC DIRECTORY

  .

   

  // Section 12 - OBJ DIRECTORY

  <%objdir(".")%>

   

  // Section 13 - BIN DIRECTORY

  <%if(exeout)%><%exeout%><%else%>.<%endif%>

   

  // User targets section. Following lines will be

  // inserted into Makefile right after the generated cleanall target.

  // The Project File editor does not edit these lines - edit the .vpj

  // directly. You should know what you are doing.

  // Section 14 - USER TARGETS

  <%marker(top)%>

  <%marker(macros)%>

  <%marker(local)%>

  <%marker(bottom)%>

  //end-user-targets

   

  // Section 15 - LIBRARY FILES

  <%foreach(libs lit_libs pure_libs)%>

  <%lib%>

  <%endfor%>

  //end-library-files

   

• Note that output is generated differently depending upon whether <%exename%>, <%sharedname%> or <%staticname%> is defined due to the if statements that were used with relation these variable names. Also, certain portions of the project file are only generated if particular variables are set.

Project Creator

• Next, you would write the FictionalProjectCreator.pm. It may be best to start with a copy of the MakeProjectCreator.pm and edit it. Change the package name to FictionalProjectCreator and have it inherit from MakeProjectBase and ProjectCreator. Then, override the methods that are needed for this particular type.

• package FictionalProjectCreator;

   

  # ************************************************************

  # Description : A Fictional Project Creator

  # Author : Chad Elliott

  # Create Date : 10/01/2004

  # ************************************************************

   

  # ************************************************************

  # Pragmas

  # ************************************************************

   

  use strict;

   

  use MakeProjectBase;

  use ProjectCreator;

   

  use vars qw(@ISA);

  @ISA = qw(MakeProjectBase ProjectCreator);

   

  # ************************************************************

  # Subroutine Section

  # ************************************************************

   

  sub convert_slashes {

    #my $self = shift;

    return 0;

  }

   

   

  sub project_file_extension {

    #my $self = shift;

    return '.fic';

  }

   

   

  sub get_dll_exe_template_input_file {

    #my $self = shift;

    return 'fictionalexe';

  }

   

   

  sub get_dll_template_input_file {

    #my $self = shift;

    return 'fictionaldll';

  }

   

   

  sub get_template {

    #my $self = shift;

    return 'fictional';

  }

   

  1;

   

• In our example, we inherit from the MakeProjectBase which provides some methods that are common to all “make” based project creators.
• We override the convert_slashes method to return 0. A zero return value tells MPC not to convert slashes to back slashes (converting slashes is useful for Windows related build tools).
• We then override the project_file_extension method to return the project file extension which is used by a method defined in the MakeProjectBase module.
• Next, we override the get_dll_exe_template_input_file and get_dll_template_input_file methods. Those methods return the specific template input file names for a dynamic executable and dynamic library, respectively.
• Lastly, we override the get_template method to return the template file name for our new project type. In our case, the method returns fictional which corresponds to the name of the template file we created earlier.
• There are many other methods that can be overridden to change the way MPC generates output. For a complete list, see the “Virtual Methods To Be Overridden” section of the Creator.pm and ProjectCreator.pm.

Workspace Creator

• The last part that you would need to write is the FictionalWorkspaceCreator.pm. This module is usually more code-intensive than its Project Creator counterpart.

• package FictionalWorkspaceCreator;

   

  # ************************************************************

  # Description : A Fictional Workspace Creator

  # Author : Chad Elliott

  # Create Date : 10/01/2004

  # ************************************************************

   

  # ************************************************************

  # Pragmas

  # ************************************************************

   

  use strict;

   

  use FictionalProjectCreator;

  use WorkspaceCreator;

   

  use vars qw(@ISA);

  @ISA = qw(WorkspaceCreator);

   

  # ************************************************************

  # Subroutine Section

  # ************************************************************

   

  sub workspace_file_name {

    my $self = shift;

    return $self->get_modified_workspace_name($self->get_workspace_name(), '.fws');

  }

   

   

  sub pre_workspace {

    my($self, $fh) = @_;

    my $crlf = $self->crlf();

   

    print $fh '<?xml version="1.0" encoding="UTF-8"?>', $crlf,

              '<!-- MPC Command -->', $crlf,

              "<!-- $0 @ARGV -->", $crlf;

  }

   

   

  sub write_comps {

    my($self, $fh) = @_;

    my $projects = $self->get_projects();

    my @list = $self->sort_dependencies($projects);

    my $crlf = $self->crlf();

   

    print $fh '<projects>', $crlf;

    foreach my $project (@list) {

      print $fh " <project path=\"$project\"/>$crlf";

    }

    print $fh "</projects>$crlf";

  }

   

   

  1;

   

   

• The first method we override from WorkspaceCreator.pm is the workspace_file_name method. It is used to determine the output file for the generated workspace.
• Second, we override the pre_workspace method, which we use to print out the generic unchanging section of our generated workspace.
• Lastly, we override the write_comps method. This method is where the bulk of the work is done in our workspace creator. A workspace creator has many sets of data available. A reference to the list of project file names can be obtained through the get_projects method; project-specific information can be obtained through the get_project_info method which returns an array reference where each array element is an array containing the project name, project dependencies and a project guid (if applicable).