docs/MPC.sgml

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
   2   <!ENTITY mpc "mpc.pl">
   3   <!ENTITY mwc "mwc.pl">
   4 ]>
   5 <!-- This file was written by Thomas Girard <thomas.g.girard@free.fr>   -->
   6 <!-- on May 2006 for the Debian GNU/Linux operating system.             -->
   7 <!-- It is mainly a plain text to DocBook conversion of the USAGE file. -->
   8 <refentry>
   9   <refmeta>
  10     <refentrytitle>MPC</refentrytitle>
  11     <manvolnum>1</manvolnum>
  12   </refmeta>
  13   <refnamediv>
  14     <refname>&mpc;, &mwc;</refname>
  15     <refpurpose>generate project and workspace files</refpurpose>
  16   </refnamediv>
  17   <refsynopsisdiv>
  18     <cmdsynopsis>
  19       <command>&mpc;</command>
  20       <arg rep="repeat"><replaceable>OPTION</replaceable></arg>
  21       <arg rep="repeat"><replaceable>FILE</replaceable></arg>
  22     </cmdsynopsis>
  23     <cmdsynopsis>
  24       <command>&mwc;</command>
  25       <arg rep="repeat"><replaceable>OPTION</replaceable></arg>
  26       <arg rep="repeat"><replaceable>FILE</replaceable></arg>
  27     </cmdsynopsis>
  28   </refsynopsisdiv>
  29   <refsect1>
  30     <title>DESCRIPTION</title>
  31     <para>
  32     <command>&mpc;</command> and <command>&mwc;</command>, the Makefile,
  33     Project and Workspace Creator generate platform and compiler specific
  34     files to automate the compilation process
  35     (e.g. <filename>GNUmakefile</filename>
  36     and <filename>Makefile.am</filename>).
  37     </para>
  38     <para>
  39     The most common way to use the Make Project Creator is to run the
  40     workspace generator (<command>&mwc;</command>).  This script will
  41     generate projects and a single workspace that contains the generated
  42     projects.  If no input
  43     <replaceable>FILE</replaceable> (<filename>.mwc</filename> file)
  44     is specified, it will recurse into
  45     the directory in which the script was started.  It looks for
  46     <filename>.mpc</filename> files and generates a project or projects
  47     for each one found.
  48     </para>
  49     <para>
  50     Most of what is stated about <command>&mwc;</command> applies to
  51     <command>&mpc;</command> except that it only generates projects.  If an
  52     input <replaceable>FILE</replaceable> (<filename>.mpc</filename> file) is
  53     not provided, the project creator will attempt to create a default
  54     project in the directory from which the script was started.
  55     </para>
  56     <variablelist>
  57       <varlistentry>
  58         <term><parameter>-global</parameter> <replaceable>file</replaceable></term>
  59         <listitem>
  60           <para>
  61           specifies the global input file.  Values stored within this file are
  62           applied to all projects.  If not specified, defaults to
  63           <filename>config/global.mpb</filename>
  64           </para>
  65         </listitem>
  66       </varlistentry>
  67       <varlistentry>
  68         <term><parameter>-include</parameter> <replaceable>directory</replaceable></term>
  69         <listitem>
  70           <para>
  71           specifies a directory to search when looking for base projects,
  72           template input files and templates.  This option can be used
  73           multiple times to add directories.  Two include directories
  74           are used by default (<filename class="directory">config</filename>
  75           and <filename class="directory">templates</filename>)
  76           </para>
  77         </listitem>
  78       </varlistentry>
  79       <varlistentry>
  80         <term><parameter>-recurse</parameter></term>
  81         <listitem>
  82           <para>
  83           recurse from the current directory and generate from all found
  84           input files.
  85           </para>
  86         </listitem>
  87       </varlistentry>
  88       <varlistentry>
  89         <term><parameter>-ti dll | lib | dll_exe | lib_exe:</parameter><replaceable>file</replaceable></term>
  90         <listitem>
  91           <para>
  92           specifies the template input file (with no extension) for the
  93           specific type, e.g. <parameter>-ti dll_exe:vc8exe</parameter>.  Each
  94           project creator has a default template input file for each type of
  95           project (<parameter>dll_exe</parameter>, <parameter>lib_exe</parameter>,
  96           <parameter>dll</parameter>, <parameter>lib</parameter>).  You can
  97           override the default template input file name with the
  98           <parameter>-ti</parameter> option.  The file must have a
  99           <filename>mpt</filename> extension and must reside within the
 100           include search directories.  NOTE: the <parameter>lib</parameter>
 101           and the <parameter>lib_exe</parameter> template input files are only
 102           used when MPC is generating static projects
 103           </para>
 104         </listitem>
 105       </varlistentry>
 106       <varlistentry>
 107         <term><parameter>-hierarchy</parameter></term>
 108         <listitem>
 109           <para>
 110           generate a workspace in a hierarchical fashion.  Forces the
 111           generation of a hierarchical workspace at each directory level in
 112           between the toplevel directory and the location of the
 113           <filename>.mpc</filename> file that is being processed.  This is the
 114           default for <parameter>make</parameter> based workspace creators.
 115           NOTE: This option has no effect when when used with
 116           <command>&mpc;</command>
 117           </para>
 118         </listitem>
 119       </varlistentry>
 120       <varlistentry>
 121         <term><parameter>-template</parameter> <replaceable>file</replaceable></term>
 122         <listitem>
 123           <para>
 124           specifies the template name (with no extension).
 125           <replaceable>file</replaceable> should have a
 126           <filename>.mpd</filename> extension and sit in one of the include
 127           search directories.  NOTE: The <parameter>-template</parameter>
 128           option overrides the template file for all types specified
 129           </para>
 130         </listitem>
 131       </varlistentry>
 132       <varlistentry>
 133         <term><parameter>-relative</parameter> <replaceable>name</replaceable>=<replaceable>var</replaceable></term>
 134         <listitem>
 135           <para>
 136           any <varname>$()</varname> variable in an mpc file that is matched to
 137           <replaceable>name</replaceable> is replaced by
 138           <replaceable>var</replaceable> only if
 139           <replaceable>var</replaceable> can be made into a relative path based
 140           on the current working directory
 141           </para>
 142         </listitem>
 143       </varlistentry>
 144       <varlistentry>
 145         <term><parameter>-base</parameter> <replaceable>project</replaceable></term>
 146         <listitem>
 147           <para>
 148           add <replaceable>project</replaceable> as a base project to each
 149           generated project file.  Do not provide a file extension, the
 150           <filename>.mpb</filename> extension will be tried first; if that
 151           fails the <filename>.mpc</filename> extension will be tried
 152           </para>
 153         </listitem>
 154       </varlistentry>
 155       <varlistentry>
 156         <term><parameter>-nocomments</parameter></term>
 157         <listitem>
 158           <para>
 159           do not place comments in the generated files
 160           </para>
 161         </listitem>
 162       </varlistentry>
 163       <varlistentry>
 164         <term><parameter>-noreldefs</parameter></term>
 165         <listitem>
 166           <para>
 167           do not try to generate default relative definitions for
 168           <varname>*_ROOT</varname>, which come from environment variables
 169           </para>
 170         </listitem>
 171       </varlistentry>
 172       <varlistentry>
 173         <term><parameter>-notoplevel</parameter></term>
 174         <listitem>
 175           <para>
 176           do not generate the top level target file.  Files are still processed,
 177           but no top level file is created.  For <command>&mwc;</command>, it
 178           says process all projects for a workspace, but do not generate the
 179           top level workspace file.  For <command>&mpc;</command>, it says
 180           process the <filename>.mpc</filename> files, but do not generate
 181           the project files
 182           </para>
 183         </listitem>
 184       </varlistentry>
 185       <varlistentry>
 186         <term><parameter>-static</parameter></term>
 187         <listitem>
 188           <para>
 189           specifies that only static projects are generated.  By default,
 190           only dynamic projects will be generated.  This parameter was
 191           previously <parameter>-static_only</parameter>.  Currently,
 192           <command>&mpc;</command> only supports generating dynamic projects
 193           or static projects, but not both during the same run.  To generate
 194           them both you must run <command>&mpc;</command> twice, once with the
 195           <parameter>-static</parameter> option and once without.
 196           Additionally, the <parameter>vc6</parameter>,
 197           <parameter>em3</parameter>, <parameter>vc7</parameter>,
 198           <parameter>vc71</parameter> and <parameter>vc8</parameter> project
 199           names will no longer automatically have
 200           <filename>_Static</filename> appended to the project name when
 201           generating static projects.  This can still be achieved by using the
 202           <parameter>-name_modifier</parameter> option.
 203           </para>
 204           <para>
 205           When generating static projects, inter-project dependencies will
 206           not be generated for libraries within <parameter>vc6</parameter>,
 207           <parameter>em3</parameter>, <parameter>vc7</parameter>,
 208           and <parameter>vc71</parameter>  workspaces.  The reason is due to
 209           the fact that each static library that depended upon another would
 210           be combined at the library creation stage, resulting in extremely
 211           large libraries.  Dependencies are handled correctly by vc8 and
 212           later.  This behavior can be modified by setting the
 213           <envar>MPC_DEPENDENCY_COMBINED_STATIC_LIBRARY</envar> environment
 214           variable.  It will force <command>&mpc;</command> to generate
 215           inter-project dependencies for libraries within a single workspace
 216           </para>
 217         </listitem>
 218       </varlistentry>
 219       <varlistentry>
 220         <term><parameter>-genins</parameter></term>
 221         <listitem>
 222           <para>
 223           generate <filename>.ins</filename> files after
 224           processing each project that can be used in conjunction with the
 225           <command>prj_install.pl</command> script to install different
 226           parts of the project (such as header files) into an alternate
 227           location
 228           </para>
 229         </listitem>
 230       </varlistentry>
 231       <varlistentry>
 232         <term><parameter>-use_env</parameter></term>
 233         <listitem>
 234           <para>
 235           use environment variables for all uses of
 236           <varname>$()</varname> instead of the relative replacement values
 237           </para>
 238         </listitem>
 239       </varlistentry>
 240       <varlistentry>
 241         <term><parameter>-value_template</parameter> <replaceable>name</replaceable><parameter>+=</parameter><replaceable>val</replaceable> | <replaceable>name</replaceable><parameter>=</parameter><replaceable>val</replaceable> | <replaceable>name</replaceable><parameter>-=</parameter><replaceable>val</replaceable></term>
 242         <listitem>
 243           <para>
 244           this option allows modification of a template input name pair.  Use
 245           <parameter>+=</parameter> to add
 246           <replaceable>val</replaceable> to the
 247           <replaceable>name</replaceable>'s value.  Use
 248           <parameter>-=</parameter> to subtract and <parameter>=</parameter> to
 249           override the value.  If a template variable value will contain
 250           spaces, it is best to enclose the whole setting in double quotes
 251           and use single quotes within the value to retain spaces (if it is
 252           necessary)
 253           </para>
 254         </listitem>
 255       </varlistentry>
 256       <varlistentry>
 257         <term><parameter>-value_project</parameter> <replaceable>name</replaceable><parameter>+=</parameter><replaceable>val</replaceable> | <replaceable>name</replaceable><parameter>=</parameter><replaceable>val</replaceable> | <replaceable>name</replaceable><parameter>-=</parameter><replaceable>val</replaceable></term>
 258         <listitem>
 259           <para>
 260           this option allows modification of a project variable
 261           assignment.  Use <parameter>+=</parameter> to add
 262           <replaceable>val</replaceable> to the
 263           <replaceable>name</replaceable>'s value.  Use
 264           <parameter>-=</parameter> to subtract and <parameter>=</parameter> to
 265           override the value.  This can be used to introduce new name value
 266           pairs to a project.  However, it must be a valid project assignment
 267           </para>
 268         </listitem>
 269       </varlistentry>
 270       <varlistentry>
 271         <term><parameter>-make_coexistence</parameter></term>
 272         <listitem>
 273           <para>
 274           if multiple <command>make</command> based project types are generated,
 275           they will be named such that they can coexist
 276           </para>
 277         </listitem>
 278       </varlistentry>
 279       <varlistentry>
 280         <term><parameter>-feature_file</parameter> <replaceable>file</replaceable></term>
 281         <listitem>
 282           <para>
 283           specifies the features file to read before processing.  These
 284           feature names can be anything, but they should correspond
 285           to values used for the <property>requires</property> and
 286           <property>avoids</property> keywords.  If a feature is required and
 287           is not enabled then the project will not be created.  If a feature
 288           is to be avoided and it is enabled then the project will not be
 289           created.  The default feature file is
 290           <filename>default.features</filename> under the
 291           <filename class="directory">config</filename> directory
 292           </para>
 293         </listitem>
 294       </varlistentry>
 295       <varlistentry>
 296         <term><parameter>-expand_vars</parameter></term>
 297         <listitem>
 298           <para>
 299           perform direct expansion, instead of performing relative replacement
 300           with either <parameter>-use_env</parameter> or
 301           <parameter>-relative</parameter> options
 302           </para>
 303         </listitem>
 304       </varlistentry>
 305       <varlistentry>
 306         <term><parameter>-features</parameter> <replaceable>features</replaceable></term>
 307         <listitem>
 308           <para>
 309           specifies the feature list to set before processing.  Values
 310           specified by this option overwrite values from features files,
 311           e.g. <parameter>-features "qos=1,ssl=0"</parameter>
 312           </para>
 313         </listitem>
 314       </varlistentry>
 315       <varlistentry>
 316         <term><parameter>-gendot</parameter></term>
 317         <listitem>
 318           <para>
 319           generate .dot files for use with <command>Graphvis</command>.
 320           This option, which is only useful with <command>&mwc;</command>,
 321           will result in the generation of .dot files for each workspace
 322           processed.  Each .dot file will contain information that can be
 323           fed to Graphvis to display the dependency information for the
 324           various projects found within the workspace.
 325           </para>
 326         </listitem>
 327       </varlistentry>
 328       <varlistentry>
 329         <term><parameter>-exclude</parameter> <replaceable>directories</replaceable></term>
 330         <listitem>
 331           <para>
 332           use this option to exclude directories or files when searching for
 333           input files.  NOTE: This option has no effect when used with
 334           <command>&mpc;</command>
 335           </para>
 336         </listitem>
 337       </varlistentry>
 338       <varlistentry>
 339         <term><parameter>-name_modifier</parameter> <replaceable>pattern</replaceable></term>
 340         <listitem>
 341           <para>
 342           modify generated workspace or project names.  The
 343           <replaceable>pattern</replaceable> passed
 344           to this parameter will have the <filename>*</filename> portion
 345           replaced with the actual output name.  For example
 346           <parameter>-name_modifier '*_Static'</parameter> will result in all
 347           workspace and project names ending in <filename>_Static</filename>,
 348           e.g. <filename>FOO_Static.dsw</filename> and
 349           <filename>FOO_Static.dsp</filename>
 350           </para>
 351         </listitem>
 352       </varlistentry>
 353       <varlistentry>
 354         <term><parameter>-apply_project</parameter></term>
 355         <listitem>
 356           <para>
 357           when used in conjunction with <parameter>-name_modifier</parameter>,
 358           it applies the name modifier to the project name also.  NOTE: this
 359           option has no effect without the
 360           <parameter>-name_modifier</parameter> option
 361           </para>
 362         </listitem>
 363       </varlistentry>
 364       <varlistentry>
 365         <term><parameter>-workers</parameter></term>
 366         <listitem>
 367           <para>
 368           Specifies number of child processes to use to generate projects.
 369           </para>
 370         </listitem>
 371       </varlistentry>
 372       <varlistentry>
 373         <term><parameter>-workers_dir</parameter></term>
 374         <listitem>
 375           <para>
 376           The directory for storing temporary output files from the child processes.
 377           The default is '/tmp/mpc' If neither -workers_dir nor -workers_port is used,
 378      -workers_dir is assumed.
 379           </para>
 380         </listitem>
 381       </varlistentry>
 382       <varlistentry>
 383         <term><parameter>-workers_port</parameter></term>
 384         <listitem>
 385           <para>
 386           The port number for the parent listener.
 387           </para>
 388         </listitem>
 389       </varlistentry>
 390       <varlistentry>
 391         <term><parameter>-version</parameter></term>
 392         <listitem>
 393           <para>
 394           print the MPC version and exit
 395           </para>
 396         </listitem>
 397       </varlistentry>
 398       <varlistentry>
 399         <term><parameter>-into</parameter> <replaceable>directory</replaceable></term>
 400         <listitem>
 401           <para>
 402           place all output files in a mirrored directory structure starting
 403           at <replaceable>directory</replaceable>
 404           </para>
 405         </listitem>
 406       </varlistentry>
 407       <varlistentry>
 408         <term><parameter>-gfeature_file</parameter> <replaceable>file</replaceable></term>
 409         <listitem>
 410           <para>
 411           specifies the global feature file.  The default value is
 412           <filename>global.features</filename> under the
 413           <filename class="directory">config</filename> directory
 414           </para>
 415         </listitem>
 416       </varlistentry>
 417       <varlistentry>
 418         <term><parameter>-language cplusplus | csharp | java | vb</parameter></term>
 419         <listitem>
 420           <para>
 421           specify the language preference.  The default is
 422           <parameter>cplusplus</parameter>
 423           </para>
 424         </listitem>
 425       </varlistentry>
 426       <varlistentry>
 427         <term><parameter>-type automake | bcb2007 | bcb2009 | bds4 | bmake | cc | em3 | ghs | html | make | nmake | sle | vc6 | vc7 | vc71 | vc8 | vc9 | vc10 | wb26</parameter></term>
 428         <listitem>
 429           <para>
 430           specifies the type of project file to generate.  This option can
 431           be used multiple times to generate multiple types.  There is no
 432           longer a default.  NOTE: The <parameter>-ti</parameter>
 433           option overrides the template input file for all types specified
 434           </para>
 435         </listitem>
 436       </varlistentry>
 437
 438     </variablelist>
 439     <refsect2>
 440       <title>MPC Codebase Configuration File</title>
 441       <para>
 442       This configuration file can be used to specify alternate locations for the
 443       MPC Configuration File.  If a base.cfg is found underneath the 'config'
 444       directory where MPC is executed, it will be read to determine the location
 445       of MPC.cfg based on the directory in which MPC was started.
 446       </para>
 447       <para>
 448       For example, if $MPC_ROOT/mwc.pl is run under /foo/bar_root/src and
 449       $MPC_ROOT/config/base.cfg contained:
 450       </para>
 451       <para>
 452       /foo/bar_root = /foo/bar_root/MPC/config
 453       </para>
 454       <para>
 455       MPC would attempt to open and read /foo/bar_root/MPC/config/MPC.cfg as the
 456       MPC Configuration File.  If the base configuration file is not present,
 457       MPC will try to use $MPC_ROOT/config/MPC.cfg as the MPC Configuration File.
 458       </para>
 459       <para>
 460       You may reference environment variables, accessed by $NAME, on either side
 461       of the equals sign.
 462       </para>
 463     </refsect2>
 464     <refsect2>
 465       <title>MPC Configuration File</title>
 466       <para>
 467       In an effort to move away from the use of environment variables, a
 468       configuration file has been introduced.  The configuration file (MPC.cfg)
 469       can contain settings to provide command line options, control logging and
 470       direct MPC to dynamic project types.
 471       </para>
 472       <para>
 473       The following keywords are allowed in the configuration file, which will
 474       be read from the 'config' directory of MPC.
 475       </para>
 476       <para>
 477         <variablelist>
 478           <varlistentry>
 479             <term><parameter>command_line</parameter></term>
 480             <listitem>
 481               <para>
 482               provide additional command line options to MPC.  The value of
 483               this setting will be prepended to the options passed to
 484               <command>&mwc;</command> or <command>&mpc;</command>
 485               </para>
 486             </listitem>
 487           </varlistentry>
 488           <varlistentry>
 489             <term><parameter>default_type</parameter></term>
 490             <listitem>
 491               <para>
 492               provide a single project type (as specified by the -type
 493               option) as the default project type
 494               </para>
 495             </listitem>
 496           </varlistentry>
 497           <varlistentry>
 498             <term><parameter>dynamic_types</parameter></term>
 499             <listitem>
 500               <para>
 501               this comma separated list points to directories in which
 502               MPC will search for Perl modules to implement additional
 503               MPC project types, base projects or template files.  This
 504               setting can be used to augment or replace functionality
 505               in MPC.  For each suitable directory found, it will add a
 506               <property>modules</property> include path for Perl to find
 507               modules, add a <property>config</property> include path to
 508               locate base projects and a <property>template</property>
 509               include path to find MPC templates.
 510               </para>
 511             </listitem>
 512           </varlistentry>
 513           <varlistentry>
 514             <term><parameter>includes</parameter></term>
 515             <listitem>
 516               <para>
 517               similar to the -include command line option, it adds the
 518               list of comma separated paths to the MPC include search paths.
 519               </para>
 520             </listitem>
 521           </varlistentry>
 522           <varlistentry>
 523             <term><envar>logging</envar></term>
 524             <listitem>
 525               <para>
 526               if this setting contains
 527               <property>info=1</property>, informational
 528               messages will be printed.  If it contains
 529               <property>warn=1</property>, warning
 530               messages will be printed.  If it contains
 531               <property>diag=1</property>, diagnostic
 532               messages will be printed.  If it contains
 533               <property>debug=1</property>, debug
 534               messages will be printed.  And lastly, if it contains
 535               <property>detail=1</property>,
 536               detail messages will be printed.  If it contains none of these,
 537               <command>&mpc;</command> will not print out any information or
 538               warnings when processing projects or workspaces.  Errors are
 539               always printed if any are encountered.
 540               </para>
 541             </listitem>
 542           </varlistentry>
 543           <varlistentry>
 544             <term><envar>verbose_ordering</envar></term>
 545             <listitem>
 546               <para>
 547               if this is set, <command>&mwc;</command> will warn the user about
 548               references to projects in the <property>after</property> keyword
 549               that have not been processed
 550               </para>
 551             </listitem>
 552           </varlistentry>
 553         </variablelist>
 554       </para>
 555     </refsect2>
 556     <refsect2>
 557       <title>ENVIRONMENT VARIABLES</title>
 558       <para>
 559         The following environment variable could affect
 560         <command>&mwc;</command> and <command>&mpc;</command>:
 561
 562         <variablelist>
 563           <varlistentry>
 564             <term><envar>MPC_DEPENDENCY_COMBINED_STATIC_LIBRARY</envar></term>
 565             <listitem>
 566               <para>
 567               see the help on <parameter>-static</parameter> parameter above
 568               </para>
 569             </listitem>
 570           </varlistentry>
 571           <varlistentry>
 572             <term><envar>MPC_GHS_UNIX</envar></term>
 573             <listitem>
 574               <para>
 575               this environment variable is only meaningful when generating
 576               the ghs project files.  By default, the ghs type assumes that it is for
 577               Windows.  If this is not the case, set this environment variable
 578               prior to running MPC
 579               </para>
 580             </listitem>
 581           </varlistentry>
 582         </variablelist>
 583       </para>
 584     </refsect2>
 585   </refsect1>
 586 </refentry>