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