| blob | 46d296b4461da39e95dc797084b6cd90102abf0a |
3 .:: 3/13/2002 ::.
5 The Makefile, Project and Workspace Creator.
6 Designed by Justin Michel and Chad Elliott.
8 A single tool (MPC) can be used to generate tool specific input (i.e.,
9 Makefile, dsp, vcproj, etc.) The generator takes platform and building
10 tool generic files (mpc files) as input which describe basic information
11 needed to generate a "project" file for various build tools. These tools
12 include Make, NMake, Visual C++ 6, Visual C++ 7, etc.
14 One of the many unique and useful features of the Makefile, Project and
15 Workspace Creator is that the project definition files can employ the idea
16 of inheritance. This feature allows a user to set up a basic base project
17 (mpb file) that can contain information that is applicable to all
18 sub-projects. Things such as include paths, library paths and inter-project
19 dependencies could be described in this base project and any project that
20 inherits from it would contain this information as well.
22 Another set of files, known as template input files (mpt files), provides
23 the generator with the necessary information to fill platform and build tool
24 specific information for dynamic and static library and binary executable
25 projects.
27 Together, the generic input files and the template input files are applied
28 toward a platform and build specific template (mpd file) to create the final
29 product (a build tool specific input file). These templates contain
30 "variables" that are filled in by the project creator with information
31 gathered through the mpc and mpt files and possibly by default values set
32 within the template itself.
34 Workspaces are defined by providing a list of mpc files in a single (mwc)
35 file. For each mpc file specified, the workspace creator (mwc.pl) calls
36 upon the project creator to generate the project. After all of the projects
37 are successfully generated, the tool specific workspace is generated
38 containing the projects and any defined inter-project dependency information
39 (if supported by the build tool). If no workspace files are provided to the
40 workspace creator, then the current directory is traversed and any mpc files
41 located will be part of the workspace that is generated.
44 Workspace Declarations
45 ----------------------
47 workspace(workspace_name) {
48 file.mpc
49 directory
50 relative/path/to/another/mwc_file
51 }
53 Workspaces can contain individual mpc files, directories or other mwc files.
54 In the case of a directory, the workspace creator will traverse it and use
55 any mpc files that are found. If another workspace file is listed in the
56 workspace files, it will be aggregated into the workspace with paths relative
57 to the directory in which the main workspace is found. These "aggregated"
58 workspaces should not inherit from any other base workspace. The workspace
59 files should have an 'mwc' extension.
61 You can exclude directories and .mpc files from a workspace using the 'exclude'
62 scope operator:
64 workspace {
65 dir1
66 dir2
68 // exclude this_dir for all project types
69 exclude {
70 dir2/this_dir
71 }
73 // exclude other_dir for vc6, vc71, vc8, and vc9 types
74 exclude(vc6, vc71, vc8, vc9) {
75 dir2/other_dir
76 }
78 // exclude unix_only for every type except gnuace and make
79 exclude(!gnuace, !make) {
80 dir2/unix_only
81 }
83 // exclude non_window for every windows project type
84 exclude(prop:windows) {
85 dir2/non_windows
86 }
88 // exclude microsoft_only for all non-microsoft project types
89 exclude(!prop:microsoft) {
90 dir2/microsoft_only
91 }
93 dir3
95 // Associate the name "other" with dir3
96 associate(other) {
97 dir3
98 }
100 specific(rpmspec) {
101 rpm_version = 1.0
102 }
103 }
105 The associate scope associates a name with one or more directories.
106 This does not add directories to a workspace, it only makes an
107 association. This may or may not have an effect on the generated
108 workspace; it depends solely upon whether the project type supports
109 associations.
111 Currently automake is the only project type that supports associations.
112 Each directory listed under an association is grouped together and
113 built conditionally based on the association name.
115 Workspaces support a 'specific' clause conceptually and syntactically similar
116 to the project 'specific' clause, described below. Any variables assigned
117 within the clause are only available to workspaces, not to projects. Two sorts
118 of assignments are possible: first are assignments to the keywords cmdline and
119 implicit (described in the section 'Workspaces', below) and the second are
120 type-specific variables. Consult the documentation for the type for details on
121 type-specific variables. Keyword assignments (cmdline and implicit) impact the
122 entire workspace, not just the 'specific' scope.
124 Finally, prop:value are properties in MPC. They are used to group
125 together common workspace/project types. More details on properties
126 in MPC can be found in the section on the 'specific' keyword in the
127 Project Declarations section below.
129 Project Declarations
130 --------------------
132 project(project_name) : baseproject, anotherbaseproject {
133 exename = foo
134 includes += "."
135 libpaths = directory
137 Source_Files {
138 file1.cpp
139 file2.cpp
140 .
141 .
142 fileN.cpp
143 }
145 Header_Files {
146 file1.h
147 file2.h
148 .
149 .
150 fileN.h
151 }
152 }
155 MPC expects all files to be listed with forward slashes (/) if a file name
156 contains a directory. Providing files with back slashes (\) can cause
157 unexpected results during generation.
159 When listing files within components (Source_Files, Header_Files, etc.), you
160 can use wild cards (*?[]) to include groups of files as can be done in shells.
161 You can exclude files by preceding the name (or wild card) with the '!', but
162 this sort of exclusion only pertains to files that exist in the directory at
163 the time of project generation. There is an additional syntax similar to
164 the '!' ('^') which works the same as the '!' except that after all of the
165 source files are added to the list (after automatic custom generated files
166 are added) these files are explicitly removed from the list.
168 The (project_name) part of the project declaration is optional. If it is
169 left off, the project name will default to the name of the mpc file without
170 the extension. Inheritance is optional.
172 If the project name or workspace name contains an asterisk (*) then the
173 default project (workspace) name will be used in its place. For example, if
174 the mpc file is named example.mpc and it contains the following:
176 project(*client) {
178 The project name will be example_client. If the any part of the modified
179 project (workspace) name contains a capital letter then each word will be
180 capitalized. For instance, if the above mpc file example was named
181 Example.mpc, then the modified project name would be Example_Client.
183 If the value set for exename contains an asterisk then the asterisk portion
184 of the name will be replaced with the current project name. The same logic
185 applies to sharedname, staticname, after and libs.
187 If multiple projects are going to be contained within a single workspace
188 (using mwc.pl), there can be no duplication of project names. This is
189 disallowed due to limitations of some workspace tools.
191 Project Keywords
192 ----------------
193 exename Specifies the name of the executable that will be created
194 sharedname Specifies the name of the shared library that will be created
195 staticname Specifies the name of the static library that will be created
196 buildflags This keyword can only be used as a source component scoped
197 setting (ie. inside the scope of Source_Files). It
198 specifies additional build flags that will be passed to the
199 compiler as the source files are being compiled.
200 dependent_upon This keyword can only be used as a header component scoped
201 setting (ie. inside the scope of Header_Files). It
202 determines which file the header file is dependent
203 upon for vc8, and vc9 only.
204 dllout If defined, specifies where the dynamic libraries will be
205 placed. This overrides libout in the dynamic case.
206 libout Specifies where the dynamic and static libraries will be placed
207 exeout Specifies where executables will be placed (Previously known
208 as install)
209 managed This keyword can be used as a global setting or as a source
210 component scoped setting (ie. inside the scope of
211 Source_Files). It specifies that the source files should be
212 compiled as managed C++. Since this is Microsoft specific, it
213 is only supported by the nmake, vc7 - vc14, and vs*
214 project types.
215 no_pch This keyword can only be used as a source component scoped
216 setting (ie. inside the scope of Source_Files). It
217 specifies that precompiled headers should not be used for
218 the source files listed within the scope of it's setting.
219 pch_header Specifies the precompiled header file name
220 pch_source Specifies the precompiled source file name
221 postbuild If this is defined in the project, the value will be
222 interpreted as commands to run after the project has been
223 successfully built. The <%..%> construct can be used within
224 this value to access template variables and functions of the
225 template parser. In addition, the following pseudo variables
226 can be used.
228 <%cat%> - Platform non-specific command to cat a file.
229 <%cmp%> - Platform non-specific compare command.
230 <%cp%> - Platform non-specific copy command.
231 <%mkdir%> - Platform non-specific mkdir command.
232 <%mv%> - Platform non-specific move command.
233 <%os%> - Returns either win32 or unix.
234 <%rm%> - Platform non-specific delete command.
235 <%rmdir%> - Platform non-specific recursive directory
236 delete command.
237 <%nul%> - Platform non-specific null device.
238 <%pathsep%>- Platform non-specific path separator (; or :).
239 <%gt%> - Project non-specific greater than sign.
240 <%lt%> - Project non-specific less than sign.
241 <%and%> - Project non-specific and sign.
242 <%or%> - Project non-specific or sign.
243 <%quote%> - Project non-specific double quote.
244 <%slash%> - Platform non-specific directory separator.
245 <%equote%> - Project non-specific escaped quote.
246 <%crlf%> - Platform non-specific line ending.
247 <%cmdsep%> - Project/platform non-specific command separator
248 which always runs the right-hand side command.
249 prebuild This is similar to postbuild except that it will be
250 performed before the build instead of after.
251 postclean This is similar to postbuild except that it will be
252 performed after cleaning up the project (the realclean
253 target for make based project types). NOTE: This is not
254 used in the IDE based project types since there is no hook
255 for such an action.
256 recurse If set to 1, MPC will recurse into directories listed under
257 component listings and add any component corresponding files
258 to the list. This keyword can be used as a global project
259 setting or a component scoped setting.
260 version Specifies the version number for the library or executable
261 macros These values will be passed as macros to the compiler.
262 libpaths Specifies 1 or more locations to find libraries
263 recursive_libpaths Specifies 1 or more locations to find libraries which will
264 be added recursively.
265 includes Specifies 1 or more locations to find include files
266 libs Specifies 1 or more libraries to link into the exe or library
267 recursive_includes Specifies 1 or more locations to find include files which
268 will be added recursively.
269 lit_libs Specifies 1 or more libraries to link into the exe or library.
270 If libraries receive a library decorator, then these will not.
271 pure_libs Specifies 1 or more libraries to link into the exe or library.
272 The values specified for this variable are passed to the
273 linker unmodified.
274 after Specifies that this project must be built after 1 or more
275 project names listed. An extended syntax is available in
276 order to associate name-value pairs with a dependency:
277 <project name[:name=value]>
278 These name-value pairs may be used in the creation of the
279 dependencies of the project.
280 custom_only Create a project that contains only custom generation
281 targets (any file type described by a Define_Custom section).
282 This will automatically be set to 1 when a project contains
283 no source or resource files, but does contain custom input
284 files.
285 dynamicflags Specifies preprocessor flags needed for dynamic libraries
286 staticflags Specifies preprocessor flags needed for static libraries
288 verbatim This allows arbitrary information to be place in a generated
289 project file. The syntax is as follows:
291 verbatim(<project type>, <location>[, 1]) {
292 ..
293 ..
294 }
296 When MPC is generating a project of type <project type> and
297 comes upon a marker that matches the <location> name, it
298 will place the text found inside the construct directly into
299 the generated project. If the third and optional parameter is
300 passed and is true, the verbatim section will be added to
301 existing verbatim settings at the same location. If you need
302 to preserve white space, the line or lines should be placed
303 inside double quotes.
305 specific This scope allows assignments that are specific to a
306 particular project type or property. The syntax is as
307 follows:
309 specific(<proj_type|prop:prop_name> [, <proj_type|prop:prop_name> ...]) {
310 lit_libs += c
311 ...
312 }
314 or
316 specific(<proj_type|prop:prop_name> [, <proj_type|prop:prop_name> ...]) {
317 lit_libs += c
318 ...
319 } else {
320 lit_libs += c_other
321 ...
322 }
324 If the else is provided, it is required to be on
325 the same line as the closing curly brace. You may
326 also negate the project type (using '!') which will cause
327 the specific to be evaluated for all types except the type
328 specified.
330 The following property names are available: borland, make,
331 microsoft, windows, and static. The table below shows which
332 properties apply to which project types. The static
333 property will be set if the -static option was supplied.
334 Additionally, a property that corresponds to the language
335 will be set (e.g., cplusplus, csharp, java, vb).
337 | borland | make | microsoft | windows |
338 ---------+---------+------+-----------+---------|
339 automake | | X | | |
340 bcb2007 | X | | | X |
341 bcb2009 | X | | | X |
342 bds4 | X | | | X |
343 bmake | X | X | | X |
344 cc | | | | X |
345 em3 | | | X | X |
346 ghs | | | | ? |
347 iar | | | | X |
348 make | | X | | |
349 nmake | | X | X | X |
350 uvis | | | | X |
351 vc* | | | X | X |
352 vs* | | | X | X |
353 wix | | | | X |
355 ? - indicates that this is controlled by the MPC_GHS_UNIX
356 environment variable.
358 If a keyword is not recognized as a valid MPC keyword, it is
359 interpreted as a template value modifier. In this
360 situation, this construct has the exact same restrictions as
361 the -value_template command line option. See the USAGE file
362 for more information.
364 Scopes are available in some of the MPC templates. These
365 scopes are created by using a template variable within a
366 <%foreach%> context. The scope will be, one at a time, each
367 space separated words within the template variable value.
368 Variables can be modified using a scope modifier. For
369 example, the word 'FOO' will be added to the template
370 variable 'defines' when it is seen in the 'Debug' scope:
372 specific {
373 Debug::defines += FOO
374 }
376 expand This scope allows the specification for a variable that is
377 found within $() to be expanded from the list of possible
378 values. These possible values can contain environment
379 variables (specified by $VAR_NAME) and plain text. If a
380 possible value contains an environment variable and that
381 variable is defined then this value is used to expand the
382 $() variable. If the environment variable is not defined
383 then this possible value is not used. The syntax is as
384 follows:
386 expand(<variable name>) {
387 <possible value 1>
388 .
389 .
390 <possible value n>
391 }
393 conditional This scope allows addition of source files conditionally
394 based on a particular project type or property as describe
395 in the 'specific' section. The syntax is as follows:
397 conditional(<proj_type|prop:prop_name> [, <proj_type|prop:prop_name> ...]) {
398 source1.cpp
399 ...
400 }
402 or
404 conditional(<proj_type|prop:prop_name> [, <proj_type|prop:prop_name> ...]) {
405 source1.cpp
406 ...
407 } else {
408 source2.cpp
409 ...
410 }
412 If the else is provided, it is required to be on
413 the same line as the closing curly brace. You may
414 also negate the project type (using '!') which will cause
415 the conditional to be evaluated for all types except the
416 type specified.
418 requires Specifies which features should be enabled in order to
419 generate the project file.
420 avoids Specifies which features should be disabled in order to
421 generate the project file.
422 webapp Determines whether the project is a Web Application or not.
423 A web application project will have no project file written
424 but the information will be included in the workspace (if
425 web applications are supported by the project type).
427 C# Specific Project Keywords
428 ----------------------------
429 dependent_upon This can only be applied to source and resx components. It
430 determines which file the source or resx file is dependent
431 upon for vc8 - vc14, vs* only.
432 generates_source This can only be applied to resx components. It indicates
433 that the resx file or files auto generates a source file for
434 vc8 - vc14, vs* only. A value of '1' indicates that the
435 resx file generates a source file and the default generator is
436 used. Any other value indicates that the resx file generates a
437 source file and the generator name is taken from the value
438 supplied. The auto generated name is created by taking the
439 resx file without the extension and appending .Designer.cs.
440 subtype This can only be applied to source and resx components. It
441 determines the SubType setting for vc8 - vc14, vs* only.
443 Custom File Definitions
444 -----------------------
445 In order to support a variety of custom build rules, MPC allows you to
446 define your own custom file types. Below is an example of a custom
447 definition.
449 project {
450 Define_Custom(MOC) {
451 automatic_in = 0
452 automatic_out = 0
453 command = $(QTDIR)/bin/moc
454 postcommand = echo <%quote%>#include <%lt%>some.h<%gt%><%quote%> <%gt%> <%temporary%> <%and%> \
455 <%cat%> <%output%> <%gt%><%gt%> <%temporary%> <%and%> \
456 <%mv%> <%temporary%> <%output%>
457 output_option = -o
458 inputext = .h
459 pre_extension = _moc
460 source_outputext = .cpp
461 }
463 MOC_Files {
464 QtReactor.h
465 }
467 Source_Files {
468 QtReactor_moc.cpp
469 }
470 }
472 The above example defines a custom file type "MOC" which describes basic
473 information about how to process the input files and what output files are
474 created. Once the custom file type is defined, MOC_Files can be defined in
475 order to specify the input files for this new file type.
477 Define_Custom definitions may use single inheritance. This is useful for
478 creating aliased names:
479 Define_Custom(QtMOC) : MOC {
480 }
482 Here is a list of keywords that can be used within the scope of
483 Define_Custom or Modify_Custom:
485 automatic This keyword is deprecated. Use automatic_in and
486 automatic_out instead.
487 automatic_in If set to 1, then attempt to automatically determine
488 which files belong to the set of input files for the
489 custom type. If set to 0, then no files are
490 automatically added to the input files. If omitted,
491 automatic_in is assumed to be 1.
492 automatic_out If set to 1, then attempt to automatically determine
493 which generated files belong to the set of components
494 (e.g., Source_Files, Header_Files, etc.) based on the
495 type of file generated from the custom command. If set
496 to 0, then no files are automatically added to the
497 various components. If omitted, automatic_out is
498 assumed to be 1.
499 command The name of the command that should be used to process
500 the input files for the custom type.
501 commandflags Any options that should be passed to the command go here.
502 dependent If this is given a value, then a dependency upon that
503 value will be given to all of the generated files.
504 The default for this is unset and no dependency will be
505 generated.
506 dependent_libs If this is given a value, then a dependency upon that
507 library value will be given to all of the generated files.
508 The format for this entry should be the basename for the
509 library (no library prefix, postfix, or extension)
510 preceded by any relative or absolute path to the library.
511 The typical use for this would be so that a project is
512 rebuilt when a library needs to be rebuilt for its
513 dependent executable. The default for this is unset and no
514 dependency will be generated.
515 inputext This is a comma separated list of input file extensions
516 that belong to the command.
517 keyword This is a special assignment that takes the form of the
518 following:
520 keyword newname = existing_custom_name
522 This has the effect of mapping newname to be the
523 same as existing_custom_name. existing_custom_name,
524 which is optional, corresponds to one of the keywords
525 available within a Define_Custom scope (except for
526 keyword). This function puts newname into the project
527 level scope such that it can be used outside of the
528 scope of the particular custom file type being defined.
529 It should be noted that the mapped keywords can not be
530 used within the scope of a 'specific' clause. It does
531 not cause an error, but it has absolutely no affect.
532 If existing_custom_name is not supplied, then the only
533 way to utilize the newname value is from within the
534 template code. ex. <%newname%>
535 libpath If the command requires an additional library path, add
536 it here.
537 output_option If the command takes an option to specify only a single
538 file output name, then set it here. Otherwise, this
539 should be omitted.
540 output_follows_input This setting defaults to 1 and indicates that output
541 files from the custom command will end up in the same
542 directory as the input files. If this is set to 0, it
543 is assumed that the output files will go into the same
544 directory as the .mpc file.
545 pch_postrule If this is set to 1, then a rule will be added to the
546 custom rule that will modify the source output files to
547 include the precompiled header file.
548 postcommand Allows a user to execute arbitrary commands after
549 the main command is run to generate the output file.
550 The following pseudo variables can be accessed from
551 within the postcommand assignment:
552 <%input%> - The input file for the original command.
553 <%output%> - The output created by the original command.
554 <%input_basename%> - The basename of the input file.
555 <%input_dirname%> - The directory of the input file.
556 <%input_noext%> - The input file with no extension.
557 <%output_basename%> - The basename of the output file.
558 <%output_dirname%> - The directory of the output file.
559 <%output_noext%> - The output file with no extension.
560 The output file can be referenced as a generic output
561 file using <%output%> or can be referenced as a
562 component file (if it matches the particular type)
563 using one of the following:
565 <%source_file%>
566 <%template_file%>
567 <%header_file%>
568 <%inline_file%>
569 <%documentation_file%>
570 <%resource_file%>
572 The output file without an extension can be referenced
573 as a generic output file using <%output_noext%> or can
574 be referenced as a component file (if it matches the
575 particular type) using one of the following:
577 <%source_file_noext%>
578 <%template_file_noext%>
579 <%header_file_noext%>
580 <%inline_file_noext%>
581 <%documentation_file_noext%>
582 <%resource_file_noext%>
584 The following are also available for use within the
585 postcommand setting. They return the extension (if
586 there is any) of the input and output files
587 respectively:
589 <%input_ext%>
590 <%output_ext%>
592 The following pseudo template variables, in addition to
593 all project settings, are valid for use within the
594 command, commandflags, dependent, postcommand and
595 output_option settings:
597 <%and%> - Project non-specific and sign.
598 <%cat%> - Platform non-specific command to cat a file.
599 <%cmdsep%> - Project/platform non-specific command
600 separator which always runs the right-hand
601 side command.
602 <%cp%> - Platform non-specific copy command.
603 <%gendir%> - The output directory specified by the
604 gendir setting.
605 <%gt%> - Project non-specific greater than sign.
606 <%lt%> - Project non-specific less than sign.
607 <%nul%> - Platform non-specific null device.
608 <%mkdir%> - Platform non-specific mkdir command.
609 <%mv%> - Platform non-specific move command.
610 <%or%> - Project non-specific or sign.
611 <%quote%> - Project non-specific double quote.
612 <%rm%> - Platform non-specific delete command.
613 <%temporary%> - A temporary file name.
614 <%prj_type%> - The project type supplied by the -type
615 option.
617 The following pseudo template variables will be set to
618 the known extension for Windows and empty on non-Windows
619 based project types.
621 <%bat%> - The extension for batch files.
622 <%cmd%> - The extension for command files.
623 <%exe%> - The extension for executable files.
625 If any referenced pseudo template variable does
626 not contain a value, then the particular setting
627 (command, commandflags, dependent, postcommand or
628 output_option) will not be used.
630 It should also be noted that use of automatically
631 generated project settings, such as sharedname, exename,
632 etc., may not exist at the time that a project setting
633 is evaluated and will end up empty. To avoid this
634 situation, explicitly set project settings that are
635 going to be used within this context.
636 pre_extension If the command produces multiple files of the same
637 extension, this comma separated list can be used to
638 specify them. For example, tao_idl creates two types of
639 files per extension (C.h, S.h, C.cpp, S.cpp, etc).
640 source_pre_extension This is the same as pre_extension except that it
641 only applies to source files.
642 inline_pre_extension This is the same as pre_extension except that it
643 only applies to inline files.
644 header_pre_extension This is the same as pre_extension except that it
645 only applies to header files.
646 template_pre_extension This is the same as pre_extension except that it
647 only applies to template files.
648 resource_pre_extension This is the same as pre_extension except that it
649 only applies to resource files.
650 documentation_pre_extension This is the same as pre_extension except that it
651 only applies to documentation files.
652 generic_pre_extension This is the same as pre_extension except that it
653 only applies to generic files.
654 pre_filename This is similar to pre_extension except that the values
655 are prepended to the file name instead of the extension.
656 source_pre_filename This is the same as pre_filename except that it
657 only applies to source files.
658 inline_pre_filename This is the same as pre_filename except that it
659 only applies to inline files.
660 header_pre_filename This is the same as pre_filename except that it
661 only applies to header files.
662 template_pre_filename This is the same as pre_filename except that it
663 only applies to template files.
664 resource_pre_filename This is the same as pre_filename except that it
665 only applies to resource files.
666 documentation_pre_filename This is the same as pre_filename except that it
667 only applies to documentation files.
668 generic_pre_filename This is the same as pre_filename except that it
669 only applies to generic files.
670 pre_dirname This is similar to pre_filename except that the
671 value is prepended to the directory portion of
672 the file name instead of the file name itself.
673 If a separate directory is desired, the
674 pre_dirname setting should end in a slash.
675 source_pre_dirname This is the same as pre_dirname except that it
676 only applies to source files.
677 inline_pre_dirname This is the same as pre_dirname except that it
678 only applies to inline files.
679 header_pre_dirname This is the same as pre_dirname except that it
680 only applies to header files.
681 template_pre_dirname This is the same as pre_dirname except that it
682 only applies to template files.
683 resource_pre_dirname This is the same as pre_dirname except that it
684 only applies to resource files.
685 documentation_pre_dirname This is the same as pre_dirname except that it
686 only applies to documentation files.
687 generic_pre_dirname This is the same as pre_dirname except that it
688 only applies to generic files.
689 source_outputext This is a comma separated list of possible source file
690 output extensions. If the command does not produce
691 source files, then this can be omitted.
692 inline_outputext This is a comma separated list of possible inline file
693 output extensions. If the command does not produce
694 inline files, then this can be omitted.
695 header_outputext This is a comma separated list of possible header file
696 output extensions. If the command does not produce
697 header files, then this can be omitted.
698 template_outputext This is a comma separated list of possible template file
699 output extensions. If the command does not produce
700 template files, then this can be omitted.
701 resource_outputext This is a comma separated list of possible resource file
702 output extensions. If the command does not produce
703 resource files, then this can be omitted.
704 documentation_outputext This is a comma separated list of possible
705 documentation file output extensions. If the
706 command does not produce documentation files, then
707 this can be omitted.
708 generic_outputext If the command does not generate any of the other output
709 types listed above, then the extensions should be listed
710 under this.
712 If the custom output can not be represented with the above output extension
713 keywords (*_outputext) and you have knowledge of the output files a priori,
714 you can represent them with the '>>' construct.
716 Below is an example that demonstrates the use of '>>'. The command takes an
717 input file name of foo.prp and produces two files that have completely
718 unrelated filenames (i.e. foo !~ hello).
720 project {
721 Define_Custom(Quogen) {
722 automatic_in = 0
723 automatic_out = 0
724 command = perl quogen.pl
725 commandflags = --debuglevel=1 --language=c++ \
726 --kernel_language=c++
727 inputext = .prp
728 keyword quogenflags = commandflags
729 }
731 Quogen_Files {
732 foo.prp >> hello.h hello.cpp
733 }
735 Source_Files {
736 hello.cpp
737 }
738 }
740 You can use the '<<' construct to represent dependencies for specific custom
741 input file. For instance, in the above example, assume that foo.prp depends
742 upon foo.in, we would represent this by adding << foo.in as shown below.
744 Quogen_Files {
745 foo.prp >> hello.h hello.cpp << foo.in
746 }
748 There is a construct that can be used within a Define_Custom section
749 called 'optional' and can be used to represent optional custom output
750 dependent upon particular command line parameters passed to the custom
751 command.
753 project {
754 Define_Custom(TEST) {
755 optional(keyword) {
756 flag_keyword(option) += value [, value]
757 }
758 }
759 }
761 In the above example, keyword can be any of the pre_extension, pre_filename
762 or keywords that end in _outputext. flag_keyword can be any of the custom
763 definition keywords, however only commandflags really make any sense.
764 Inside the parenthesis, the flag_keyword value is searched for the 'option'
765 value. If it is found, then the 'value' after the += is added to the list
766 specified by 'keyword'. This can also be negated by prefixing 'option' with
767 an exclamation point (!).
769 project {
770 Define_Custom(IDL) {
771 source_pre_extension = C, S
772 optional(source_pre_extension) {
773 commandflags(-GA) += A
774 }
775 }
776 }
778 In the preceding example, the source_pre_extension contains C and S. The
779 optional clause can be read as follows: If 'commandflags' contains -GA then
780 add A to source_pre_extension.
782 Particular output extensions are not required. However at least one output
783 extension type is required in order for MPC to generate a target. Within
784 graphical build environments, the custom input file will be listed
785 regardless of the presence of an extension definition. In this case, the
786 input file will be "excluded" from the build.
788 For custom file types, there are a few keywords that can be used within the
789 custom file type input lists: command, commandflags, dependent,
790 dependent_libs, gendir and postcommand. These keywords (except for gendir)
791 can be used to augment or override the values of the same name defined in a
792 Define_Custom section. gendir can be used to specify the directory in which
793 the generated output will go. Below is an example:
795 MOC_Files {
796 commandflags += -nw
797 gendir = moc_generated
798 QtReactor.h
799 }
801 Source_Files {
802 moc_generated/QtReactor_moc.cpp
803 }
805 In the above example, the generated file (QtReactor_moc.cpp) is placed in
806 the moc_generated directory and the -nw option is added to commandflags.
807 It should be noted that if the custom file definition does not set the
808 output_option then you must provide the necessary options in
809 commandflags to ensure that the generated output goes into the directory
810 specified by gendir.
812 The following example illustrates the use of the keyword mapping capability
813 of the Define_Custom:
815 project {
816 Define_Custom(CIDL) {
817 automatic_in = 0
818 automatic_out = 0
819 command = $(CIAO_ROOT)/bin/cidlc
820 commandflags = -I$(TAO_ROOT)/tao -I$(TAO_ROOT)/orbsvcs/orbsvcs --
821 inputext = .cidl
822 source_outputext = _svnt.cpp
823 generic_outputext = E.idl
825 // Allow cidlflags to be used outside the scope of CIDL_Files
826 keyword cidlflags = commandflags
827 }
829 // This will get added to all commandflags for CIDL_Files
830 cidlflags += --some_option
832 CIDL_Files {
833 // This will have a combination of the original commandflags plus
834 // the value added to cidlflags above.
835 file.cidl
836 }
838 CIDL_Files {
839 // This will have a combination of the original commandflags plus
840 // the value added to cidlflags above plus the value added to
841 // cidlflags here.
842 cidlflags += --another_option
843 another_file.cidl
844 }
845 }
847 A Modify_Custom section can be used to modify an existing custom definition.
848 The Define_Custom must be processed prior to processing a Modify_Custom
849 section; otherwise, an error will occur.
851 Special type of feature project
852 -------------------------------
853 A feature project contains information as a project would, but can only
854 be a base project and will only be added to a sub project if the features
855 that it requires (or avoids) are present.
857 A feature definition requires at least one feature name. A name by itself
858 specifies that the feature is required. A '!' in front of the feature name
859 indicates that the feature must be disabled. There may be more than one
860 feature listed between the parenthesis and they must be comma separated.
861 Each feature will be logically anded together.
863 The following feature definition requires that the qt feature be enabled.
865 feature(qt) {
866 Define_Custom(MOC) {
867 automatic_in = 0
868 automatic_out = 0
869 command = $(QTDIR)/bin/moc
870 output_option = -o
871 inputext = .h
872 pre_extension = _moc
873 source_outputext = .cpp
874 }
876 MOC_Files {
877 QtSpecific.h
878 }
880 Source_Files {
881 QtSpecific_moc.cpp
882 }
883 }
885 Assuming that the above feature definition is stored in a file named
886 qt_specific.mpb, an mpc project could inherit from it and would only receive
887 the feature definition if the qt feature was enabled.
889 project: qt_specific {
890 ...
891 }
894 Feature Files
895 -------------
896 Features are enabled and disable within feature files or through the use of
897 the -features option (see USAGE for more details). The first feature file
898 read is always global.features found in the config directory. The second
899 feature file read is the project type name with .features appended
900 (ex. vc71.features, make.features, etc.) which must be located in the same
901 directory as the global.features file. Lastly, the file specified by the
902 -feature_file option is read if this option is used.
904 Each successive feature file has precedence over the previous. That is,
905 if a feature has already been set previously it is overridden. The
906 -features option has precedence over feature files.
908 Special Keywords Available to Templates
909 ---------------------------------------
910 project_name This contains the name of the project.
911 project_file This contains the name of the output file.
912 guid This is used by the VC7 project and workspace creator.
913 configurations When used within a foreach context, this info (each
914 configuration) is gathered for use with the VC7 workspace
915 creator.
916 flag_overrides Used to determine flags that have been overridden on a per
917 file basis.
918 custom_types The list of custom file types that may have been defined
919 in the mpc file or a base project.
920 fornotlast Insert the text on every foreach iteration except the last.
921 forlast Insert the text only on the last foreach iteration.
922 fornotfirst Insert the text on every foreach iteration except the first.
923 forfirst Insert the text only on the first foreach iteration.
924 forcount By default, a one based index number of the foreach
925 iterations. The base can be modified by providing a base
926 number in the foreach as in the following examples:
928 <%foreach(4, includes)%>
929 ...
930 <%endfor%>
933 <%foreach(include, 4, includes)%>
934 ...
935 <%endfor%>
937 If the list variable ('includes' in the above example) is a function call,
938 it is necessary to provide both a variable name and a base count number.
940 Project Variable and Template Input Variable Interaction
941 --------------------------------------------------------
942 Project variables and template input variables are separate entities and in
943 the context of the TemplateParser, template input variables have precedence
944 over project variables.
946 This means that if the project keyword 'libout' is set in an MPC project and
947 is set as a template input variable, the template input variable value will
948 be used. There are exceptions to this rule. The following list shows the
949 project keywords that have their MPC project value appended to the template
950 input value (if there is a template input value).
952 libpaths
953 includes
954 libs
955 lit_libs
956 pure_libs
957 dynamicflags
958 staticflags
959 requires
960 avoids
961 macros
963 Workspaces
964 ----------
965 Workspaces (mwc files) can have assignments similar to projects. There are
966 currently only two assignments allowed.
968 The first is 'cmdline'. The values given to the cmdline assignment will be
969 processed as command line options, but only to the projects that are
970 contained within the workspace (or the scope of the assignment). All
971 command line options are valid for cmdline, except for the following:
972 -exclude, -for_eclipse, -gendot, -gfeature_file, -into, -make_coexistence,
973 -noreldefs, and -recurse.
975 The second assignment is 'implicit'. This assignment takes two different
976 types of values. It takes a boolean value (0 or 1) to indicate that an
977 implicit project should be created in directories that contain no mpc file,
978 but contain project related files (source, headers, etc.). The default
979 value for implicit is 0. It also takes a character string that represents a
980 base project (similar to the -base option). In this case, implicit is
981 enabled and each implicitly generate project file will have the base project
982 or base projects (when addition is used) when the project is created.
984 Defaulting Behavior
985 -------------------
986 1) If a project name is not specified:
988 it will be defaulted to the name of the mpc file without the extension
990 2) If a particular list is not specified (Source_Files, Header_Files, etc.):
992 all of the files in the directory will be added to the corresponding list
993 by extension
995 3) If the custom type is automatic (both input and output) and custom files
996 (ex., idl files) exist in the directory and the custom files components
997 (ex., IDL_Files) are left defaulted (i.e. not listed) or the custom files
998 components are specified and none of the custom generated files are listed
999 in the corresponding lists:
1001 the custom files are added to the custom files component list if they
1002 weren't specified and all of the (would be) generated files will be added
1003 to the front of the corresponding lists (source, inline and header lists)
1005 4) If files are listed in the Source_Files list and a corresponding header or
1006 inline file exists:
1008 the corresponding file will be added to the corresponding list (if it
1009 isn't already there)
1011 5) If a sharedname is specified and staticname is not:
1013 staticname is assigned the sharedname value (the same applies if
1014 staticname is specified and sharedname is not)
1016 6) If exename is specified then the project target is considered an
1017 executable. If neither exename, sharedname or staticname are used and
1018 any of the source files listed contains a language dependent "main", then
1019 the project target is considered an executable, otherwise it is considered
1020 a library.
1022 7) If pch_header is not specified and a header file matches *_pch.h:
1024 it is assumed to be the precompiled header file (the same applies to
1025 pch_source)
1027 Processing Order
1028 ----------------
1029 1) Project file is read
1030 2) Template input file is read
1031 3) Template file is read
1032 4) Output project is written