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