| blob | c0c8dfa789d3ec4c8b0f5b4721bd88b83fbcce65 |
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 | 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]
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.
116 The default global input file (config/global.mpb) is used if -global
117 is not specified on the command line.
119 Two include directories are used by default (config and templates).
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.
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.
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.
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.
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.
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.
152 The -static option can be used to generate only static project files.
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.
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.
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.
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.)
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.
185 The -noreldefs option says not to generate default relative definitions for
186 *_ROOT (which comes from environment variables).
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.
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.
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.
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.
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.
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.
223 mwc.pl -value_template "configurations=Debug Release 'Memcheck Debug' 'Memcheck Release'"
226 Running only the Project Generator
227 ----------------------------------
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.
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.
242 For example, if $MPC_ROOT/mwc.pl is run under /foo/bar_root/src and
243 $MPC_ROOT/config/base.cfg contained:
245 /foo/bar_root = /foo/bar_root/MPC/config
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.
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.
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.
268 The following keywords are allowed in the configuration file, which will be
269 read from the 'config' directory of MPC.
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.
307 Below is an example configuration file:
309 // MPC configuration file
310 dynamic_types = $ACE_ROOT/bin/MakeProjectCreator
311 logging = info=1 warn=1
312 verbose_ordering = 1
315 Environment Variables
316 ---------------------
318 MPC_DEPENDENCY_COMBINED_STATIC_LIBRARY - See the -static section above.
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.
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.