docs/USAGE

   1 Running the Workspace Generator
   2 -------------------------------
   3
   4 The most common way to use the Make Project Creator is to run the
   5 workspace generator (mwc.pl).  This script will generate projects and a
   6 single workspace that contains the generated projects.  If no input file
   7 (.mwc file) is specified, it will recurse into the directory in which the
   8 script was started.  It looks for .mpc files and generates a project or
   9 projects for each one found.
  10
  11
  12 Usage: mwc.pl [-global <file>] [-include <directory>] [-recurse]
  13               [-ti <dll | lib | dll_exe | lib_exe>:<file>] [-hierarchy]
  14               [-template <file>] [-relative NAME=VAL] [-base <project>]
  15               [-noreldefs] [-notoplevel] [-static] [-genins] [-use_env]
  16               [-value_template <NAME+=VAL | NAME=VAL | NAME-=VAL>]
  17               [-value_project <NAME+=VAL | NAME=VAL | NAME-=VAL>]
  18               [-make_coexistence] [-feature_file <file name>] [-gendot]
  19               [-expand_vars] [-features <feature definitions>]
  20               [-exclude <directories>] [-name_modifier <pattern>]
  21               [-apply_project] [-version] [-into <directory>]
  22               [-gfeature_file <file name>] [-nocomments]
  23               [-relative_file <file name>] [-for_eclipse]
  24               [-workers <#>] [-workers_dir <dir> | -workers_port <#>]
  25               [-language <cplusplus | csharp | java | vb>]
  26               [-type <automake | bcb2007 | bcb2009 | bds4 | bmake | cc | cdt6 |
  27                       cdt7 | em3 | ghs | html | iar | make | nmake | rpmspec |
  28                       sle | uvis | vc6 | vc7 | vc8 | vc9 | vc10 | vc11 | vc12 |
  29                       vc14 | vs2017 | vs2019 | vc71 | wb26 | wb30 | wix>]
  30               [files]
  31
  32        -base           Add <project> as a base project to each generated
  33                        project file.  Do not provide a file extension, the
  34                        .mpb extension will be tried first; if that fails the
  35                        .mpc extension will be tried.
  36        -exclude        Use this option to exclude directories or files when
  37                        searching for input files.
  38        -expand_vars    Perform direct expansion, instead of performing relative
  39                        replacement with either -use_env or -relative options.
  40        -feature_file   Specifies the feature file to read before processing.
  41                        The default feature file is default.features under the
  42                        config directory.
  43        -features       Specifies the feature list to set before processing.
  44        -for_eclipse    Generate files for use with eclipse.  This is only
  45                        useful for make based project types.
  46        -gendot         Generate .dot files for use with Graphviz.
  47        -genins         Generate .ins files for use with prj_install.pl.
  48        -gfeature_file  Specifies the global feature file.  The
  49                        default value is global.features under the
  50                        config directory.
  51        -global         Specifies the global input file.  Values stored
  52                        within this file are applied to all projects.
  53        -hierarchy      Generate a workspace in a hierarchical fashion.
  54        -include        Specifies a directory to search when looking for base
  55                        projects, template input files and templates.  This
  56                        option can be used multiple times to add directories.
  57        -into           Place all output files in a mirrored directory
  58                        structure starting at <directory>.  This should be a
  59                        full path.  If any project within the workspace is
  60                        referenced via a full path, use of this option is
  61                        likely to cause problems.
  62        -language       Specify the language preference; possible values are
  63                        [cplusplus, csharp, java, vb].  The default is
  64                        cplusplus.
  65        -make_coexistence If multiple 'make' based project types are
  66                        generated, they will be named such that they can coexist.
  67        -name_modifier  Modify output names.  The pattern passed to this
  68                        parameter will have the '*' portion replaced with the
  69                        actual output name.  Ex. *_Static
  70        -apply_project  When used in conjunction with -name_modifier, it applies
  71                        the name modifier to the project name also.
  72        -nocomments     Do not place comments in the generated files.
  73        -noreldefs      Do not try to generate default relative definitions.
  74        -notoplevel     Do not generate the top level target file.  Files
  75                        are still processed, but no top level file is created.
  76        -recurse        Recurse from the current directory and generate from
  77                        all found input files.
  78        -relative       Any $() variable in an mpc file that is matched to NAME
  79                        is replaced by VAL only if VAL can be made into a
  80                        relative path based on the current working directory.
  81                        This option can be used multiple times to add multiple
  82                        variables.
  83        -relative_file  Specifies the relative file to read before processing.
  84                        The default relative file is default.rel under the
  85                        config directory.
  86        -static         Specifies that only static projects will be generated.
  87                        By default, only dynamic projects are generated.
  88        -template       Specifies the template name (with no extension).
  89        -workers        Specifies number of child processes to use to generate
  90                        projects.
  91        -workers_dir    The directory for storing temporary output files
  92                        from the child processes.  The default is '/tmp/mpc'
  93                        If neither -workers_dir nor -workers_port is used,
  94                        -workers_dir is assumed.
  95        -workers_port   The port number for the parent listener. If neither
  96                        -workers_dir nor -workers_port is used, -workers_dir
  97                        is assumed.
  98        -ti             Specifies the template input file (with no extension)
  99                        for the specific type (ex. -ti dll_exe:vc8exe).
 100        -type           Specifies the type of project file to generate.  This
 101                        option can be used multiple times to generate multiple
 102                        types.  There is no longer a default.
 103        -use_env        Use environment variables for all uses of $() instead
 104                        of the relative replacement values.
 105        -value_project  This option allows modification of a project variable
 106                        assignment.  Use += to add VAL to the NAME's value.
 107                        Use -= to subtract and = to override the value.
 108                        This can be used to introduce new name value pairs to
 109                        a project.  However, it must be a valid project
 110                        assignment.
 111        -value_template This option allows modification of a template input
 112                        name value pair.  Use += to add VAL to the NAME's
 113                        value.  Use -= to subtract and = to override the value.
 114        -version        Print the MPC version and exit.
 115
 116 The default global input file (config/global.mpb) is used if -global
 117 is not specified on the command line.
 118
 119 Two include directories are used by default (config and templates).
 120
 121 Each project creator has a default template input file for each type of
 122 project (dll_exe, lib_exe, dll, lib).  You can override the default template
 123 input file name with the -ti option.  The file must have a 'mpt' extension
 124 and must reside within the include search directories.  NOTE: the 'lib' and
 125 the 'lib_exe' template input files are only used when MPC is generating
 126 static projects.
 127
 128 The -exclude option is used to exclude directories when searching for input
 129 files.  NOTE: This option has no effect when used with mpc.pl.
 130
 131 The -gendot option (useful only to mwc.pl) will result in the generation of
 132 .dot files for each workspace processed.  Each .dot file will contain
 133 information that can be fed to Graphvis to display the dependency
 134 information for the various projects found within the workspace.
 135
 136 The -genins option will cause MPC to generate an "install" file after
 137 processing each project that can be used in conjunction with the
 138 prj_install.pl script to install different parts of the project (such as
 139 header files) into an alternate location.
 140
 141 The -hierarchy option is used to force the generation of a hierarchical
 142 workspace at each directory level in between the toplevel directory and the
 143 location of the mpc file that is being processed.  This is the default for
 144 "make" based workspace creators.  NOTE: This option only has an effect when
 145 passed to mwc.pl.
 146
 147 The -template option is used to override the default template name.  This
 148 file should have a .mpd extension and sit in one of the include search
 149 directories.  NOTE: The -template option overrides the template file for all
 150 types specified.
 151
 152 The -static option can be used to generate only static project files.
 153
 154 The -static_only option has been replaced by the -static option.  Currently,
 155 MPC only supports generating dynamic projects or static projects, but not
 156 both during the same run.  To generate them both you must run MPC twice, once
 157 with the -static option and once without.  Additionally, the vc6, em3, vc7,
 158 vc71 and vc8 project names will no longer automatically have _Static
 159 appended to the project name when generating static projects.  This can
 160 still be achieved by using the -name_modifier option.
 161
 162 When generating static projects, inter-project dependencies will not be
 163 generated for libraries within vc6, em3, vc7 and vc71 workspaces.  The
 164 reason is due to the fact that each static library that depended upon another
 165 would be combined at the library creation stage, resulting in extremely large
 166 libraries.  Dependencies are handled correctly by vc8 and later.
 167
 168 This behavior can be modified by setting the
 169 MPC_DEPENDENCY_COMBINED_STATIC_LIBRARY environment variable.  It will force
 170 MPC to generate inter-project dependencies for libraries within a single
 171 workspace.
 172
 173 The -name_modifier option can be used to modify the generated workspace or
 174 project name.  The parameter to the -name_modifier option is a pattern where
 175 an asterisk (*) within the pattern is replaced by the actual workspace or
 176 project name.  Thus, passing -name_modifier '*_Static' to mwc.pl will result
 177 in all workspace and project names ending in _Static. (Ex. FOO_Static.dsw,
 178 FOO_Static.dsp, etc.)
 179
 180 The -apply_project option, when used in conjunction with the -name_modifier
 181 option, causes MPC to apply the name modifier to the project name in
 182 addition to the workspace and project file names.  This option has no effect
 183 outside the scope of the -name_modifier option.
 184
 185 The -noreldefs option says not to generate default relative definitions for
 186 *_ROOT (which comes from environment variables).
 187
 188 The -notoplevel option tells mwc.pl to generate all projects for a
 189 workspace, but do not generate the top level workspace file.  For mpc.pl, it
 190 says process the mpc files, but do not generate the project files.
 191
 192 The -recurse option is used to search for all files that could be processed
 193 from the current directory and its sub-directories.  If directories are
 194 passed in a comma separated list (e.g -recurse=examples,apps,TAO), then
 195 those directories will be excluded when searching for project or workspace
 196 files.
 197
 198 The -type option can be used multiple times on the same command line to
 199 generate projects of different types per mpc file.  NOTE: The -ti option
 200 overrides the template input file for all types specified.
 201
 202 The -feature_file specifies a file to be read that enables or disables
 203 features.  These feature names can be anything, but they should correspond
 204 to values used for the 'requires' and 'avoids' keywords.  If a feature is
 205 required and is not enabled then the project will not be created.  If a
 206 feature is to be avoided and it is enabled then the project will not be
 207 created.
 208
 209 The -features specifies additional list of features values. Values
 210 specified by this option overwrite values from features files.
 211 Example:
 212 mwc.pl -features "qos=1,ssl=0" ace.mwc
 213 The -features option can be used multiple times on the same command line, the
 214 effect is the same as if the parameters had been specified with a single
 215 -features options, with the parameters joined by commas.
 216
 217 The -value_template option can be used to set various template variables.
 218 If a template variable value will contain spaces, it is best to enclose the
 219 whole setting in double quotes and use single quotes within the value to
 220 retain spaces (if it is necessary).  Below is an example where the value
 221 will have spaces and some spaces need to be retained.
 222
 223 mwc.pl -value_template "configurations=Debug Release 'Memcheck Debug' 'Memcheck Release'"
 224
 225
 226 Running only the Project Generator
 227 ----------------------------------
 228
 229 Most of what is stated about the Workspace Generator applies to the Project
 230 Generator except that it only generates projects.  If an input file (.mpc
 231 file) is not provided, the project creator will attempt to create a default
 232 project in the directory from which the script was started.
 233
 234
 235 MPC Codebase Configuration File
 236 -------------------------------
 237 This configuration file can be used to specify alternate locations for the
 238 MPC Configuration File.  If a base.cfg is found underneath the 'config'
 239 directory where MPC is executed, it will be read to determine the location
 240 of MPC.cfg based on the directory in which MPC was started.
 241
 242 For example, if $MPC_ROOT/mwc.pl is run under /foo/bar_root/src and
 243 $MPC_ROOT/config/base.cfg contained:
 244
 245 /foo/bar_root = /foo/bar_root/MPC/config
 246
 247 MPC would attempt to open and read /foo/bar_root/MPC/config/MPC.cfg as the
 248 MPC Configuration File.  If the base configuration file is not present,
 249 MPC will try to use $MPC_ROOT/config/MPC.cfg as the MPC Configuration File.
 250
 251 You may reference environment variables, accessed by $NAME, on either side of
 252 the equals sign.  In either this file or the MPC Configuration File
 253 (see below), an alternate form of environment variable reference may be used
 254 for variables which are not expected to be defined in all scenarios.  These
 255 variables use the syntax $?NAME instead of $NAME.  With this syntax, if the
 256 environment variable NAME is not defined, no error or warning is printed by
 257 MPC, and the entire substring starting with $?NAME until the next whitespace is
 258 expanded to the empty string.
 259
 260
 261 MPC Configuration File
 262 ----------------------
 263 In an effort to move away from the use of environment variables, a
 264 configuration file has been introduced.  The configuration file (MPC.cfg)
 265 can contain settings to provide command line options, control logging and
 266 direct MPC to dynamic project types.
 267
 268 The following keywords are allowed in the configuration file, which will be
 269 read from the 'config' directory of MPC.
 270
 271 command_line     - Provide additional command line options to MPC.  The
 272                    value of this setting will be prepended to the options
 273                    passed to mwc.pl or mpc.pl.
 274 default_type     - Provide a single project type (as specified by the -type
 275                    option) as the default project type.
 276 dynamic_types    - This comma separated list points to directories in which
 277                    MPC will search for Perl modules to implement additional
 278                    MPC project types, base projects or template files.  This
 279                    setting can be used to augment or replace functionality
 280                    in MPC.  For each suitable directory found, it will add a
 281                    'modules' include path for Perl to find modules, add a
 282                    'config' include path to locate base projects and a
 283                    'template' include path to find MPC templates.
 284 includes         - Similar to the -include command line option, it adds the
 285                    list of comma separated paths to the MPC include search
 286                    paths.
 287 logging          - If this setting contains info=1, informational messages
 288                    will be printed.  If it contains warn=1, warning messages
 289                    will be printed.  If it contains diag=1, diagnostic
 290                    messages will be printed.  If it contains debug=1, debug
 291                    message will be printed.  And lastly, if it contains
 292                    detail=1, detail messages will be printed.  If it
 293                    contains none of these, MPC will not print out any
 294                    information or warnings when processing projects or
 295                    workspaces.  Errors are always printed if any are
 296                    encountered.  The default is warn=1 diag=1 detail=1.
 297 main_functions   - Provide additional main functions to be recognized in
 298                    conjunction with automatic executable project
 299                    recognition.  The value assigned should be of the form
 300                    <language>:<func name>[, <language>:<func name>]*.  A
 301                    function can be specified for all languages by only
 302                    providing the function name.
 303 verbose_ordering - If this is set, mwc.pl will warn the user about
 304                    references to projects in the 'after' keyword that have
 305                    not been processed.
 306
 307 Below is an example configuration file:
 308
 309 // MPC configuration file
 310 dynamic_types = $ACE_ROOT/bin/MakeProjectCreator
 311 logging = info=1 warn=1
 312 verbose_ordering = 1
 313
 314
 315 Environment Variables
 316 ---------------------
 317
 318 MPC_DEPENDENCY_COMBINED_STATIC_LIBRARY - See the -static section above.
 319
 320 MPC_GHS_UNIX - This environment variable is only meaningful when generating
 321 the ghs project files.  By default, the ghs type assumes that it is for
 322 Windows.  If this is not the case, set this environment variable prior to
 323 running MPC.
 324
 325 MPC_USE_WIN_COMMANDS - Setting this causes the Windows related pseudo
 326 template variables to be used regardless of the type of project being
 327 generated.