path: root/bin/MakeProjectCreator/README

The Makefile, Project and Workspace Creator.
Designed by Justin Michel (michel_j@ociweb.com) and Chad Elliott.
Implemented by Chad Elliott (elliott_c@ociweb.com).


A single tool (mpc.pl) can be used to generate tool specific input (i.e.
Makefile, dsp, vcproj, etc).  The generator takes platform and building
tool generic files (mpc files) as input which describe basic information
needed to generate a "project" file for various build tools.  These tools
include GNU Make, NMake, Visual C++ 6, Visual C++ 7, etc.

One of the many unique and useful features of the Makefile, Project and
Workspace Creator is that the project definition files can employ the idea
of inheritance.  This feature allows a user to set up a basic base project
(mpb file) that can contain information that is applicable to all
sub-projects.  Things such as include paths, library paths and inter-project
dependencies could be described in this base project and any project that
inherits from it would contain this information as well.

Another set of files, known as template input files (mpd files), provides
the generator with the necessary information to fill platform and build
tool specific information for dynamic and static library and binary
executable projects.

Together, the generic input files and the template input files are applied
toward a platform and build specific template (mpt file) to create the final
product (a build tool specific input file).  These templates contain
"variables" that are filled in by the project creator with information
gathered through the mpc and mpd files and possibly by default values set
within the template itself.

Workspaces are defined by providing a list of mpc files in a single (mwc)
file.  For each mpc file specified, the workspace creator (mwc.pl) calls
upon the project creator to generate the project.  After all of the projects
are successfully generated, the tool specific workspace is generated
containing the projects and any defined inter-project dependency information
(if supported by the build tool).  If no workspace files are provided to the
workspace creator, then the current directory is traversed and any mpc files
located will be part of the workspace that is generated.


Workspace Declarations
----------------------

workspace(workspace_name) {
  file.mpc
  directory
}

Workspaces can contain individual mpc files or directories.  In the case of
a directory, the workspace creator will traverse it and use any mpc files
that are found.  The workspace files should have an 'mwc' extension.


Project Declarations
--------------------

project(project_name) : baseproject, anotherbaseproject {
  exename   = foo
  includes += "."
  libpaths  = directory
  idlflags -= -Sc

  Source_Files {
    file1.cpp
    file2.cpp
    .
    .
    fileN.cpp
  }

  Header_Files {
    file1.h
    file2.h
    .
    .
    fileN.h
  }
}


The (project_name) part of the project declaration is optional.  If it is
left off, the project name will default to the name of the mpc file without
the extension.  Inheritance is optional.


Project Keywords
----------------
exename		Specifies the name of the executable that will be created
sharedname	Specifies the name of the shared library that will be created
staticname	Specifies the name of the static library that will be created
dllout		(Windows Only) Specifies where the dll will be placed
libout		(Windows Only) Specifies where the lib will be placed
install		Specifies where the executable (or library non-Windows) will go
idlflags	Specifies the idl flags to be used when processing idl files
idlgendir       Specifies the output directory for idl generated files.
                If a listed idl file has a directory as part of the name,
                the generated files will go in that directory unless
                idlgendir specifies otherwise.
idlpreprocessor	Simple assignment used in the gnu template only
pch_header	Specifies the precompiled header file name
pch_source	Specifies the precompiled source file name
ssl             Specifies that the project will use ssl
tao		Specifies that the project will use TAO
version         Specifies the version number for the library or executable

libpaths	Specifies 1 or more locations to find libraries
includes	Specifies 1 or more locations to find include files
libs		Specifies 1 or more libraries to link into the exe or library
defaultlibs	Specifies 1 or more default libraries to link in
depends         Specifies 1 or more project names upon which this project depends
dllflags	Specifies preprocessor flags needed for dll's
libflags	Specifies preprocessor flags needed for lib's

verbatim        This allows arbitrary information to be place in a generated
                project file.  The syntax is as follows:

                verbatim(<project type>, <location>) {
                  ..
                  ..
                }

                When MPC is generating a project of type <project type> and
                comes upon a marker that matches the <location> name, it
                will place the text found inside the construct directly into
                the generated project.  If you need to preserve white space,
                the line or lines should be placed inside double quotes.

The Following are GNU only:
requires        Specifies which tao macros should be set to build the target
avoids          Specifies which tao macros should not be set to build the target
compname        Specifies the argument to pass to the ace_components script
comps           Specifies which components are required to build the target
tagname         Specifies the make macro to check before building the target
tagchecks       Specifies the values for tagname to check


Custom File Definitions
-----------------------
In order to support a variety of custom build rules, MPC allows you to
define your own custom file types.  Below is an example of a custom
definition.

project {
  Define_Custom(MOC) {
    automatic        = 0
    command          = $(QTDIR)/bin/moc
    output_option    = -o
    inputext         = .h
    pre_extension    = _moc
    source_outputext = .cpp
  }

  MOC_Files {
    QtReactor.h
  }

  Source_Files {
    QtReactor_moc.cpp
  }
}

The above example defines a custom file type "MOC" which describes basic
information about how to process the input files and what output files are
created.  Once the custom file type is defined, MOC_Files can be defined in
order to specify the input files for this new file type.

Here is a list of keywords that can be used within the scope of
Define_Custom:

automatic           If set to 1, then attempt to automatically determine
                    which files belong to the set of input files for the
                    custom type.  If set to 0, then no files are
                    automatically added to the input files.  If omitted,
                    then automatic is assumed to be 1.  Custom file types
                    that are automatic will have the side effect of possibly
                    adding files to Source_Files, Inline_Files, Header_Files
                    Template_Files, Resource_Files and Documenation_Files
                    depending on which extension types the command generates.
command             The name of the command that should be used to process
                    the input files for the custom type.
commandflags        Any options that should be passed to the command go here.
inputext            This is a comma separated list of input file extensions
                    that belong to the command.
output_option       If the command takes an option to specify a single file
                    output name, then set it here.  Otherwise, this should be
                    omitted.
pre_extension       If the command produces multiple files of the same
                    extension, this comma separated list can be used to
                    specify them.  For example, tao_idl creates two types of
                    files per extension (C.h, S.h, C.cpp, S.cpp, etc).
pre_filename        This is similar to pre_extension except that the values
                    are prepended to the file name instead of the extension.
source_outputext    This is a comma separated list of possible source file
                    output extensions.  If the command does not produce
                    source files, then this can be omitted.
inline_outputext    This is a comma separated list of possible inline file
                    output extensions.  If the command does not produce
                    inline files, then this can be omitted.
header_outputext    This is a comma separated list of possible header file
                    output extensions.  If the command does not produce
                    header files, then this can be omitted.
template_outputext  This is a comma separated list of possible template file
                    output extensions.  If the command does not produce
                    template files, then this can be omitted.
resource_outputext  This is a comma separated list of possible resource file
                    output extensions.  If the command does not produce
                    resource files, then this can be omitted.
documenation_outputext  This is a comma separated list of possible
                        documentation file output extensions.  If the
                        command does not produce documenation files, then
                        this can be omitted.

For custom file types, there are two keywords that can be used within the
custom file type input lists: commandflags and gendir.  The commandflags can
be used to augment or override the commandflags defined in the Define_Custom
section.  gendir can be used (only if output_option is set in Define_Custom)
to specify the directory in which the generated output will go.  Below is an
example:

  MOC_Files {
    commandflags += -nw
    gendir = moc_generated
    QtReactor.h
  }

  Source_Files {
    moc_generated/QtReactor_moc.cpp
  }

In the above example, the generated file (QtReactor_moc.cpp) is placed in
the moc_generated directory and the -nw option is added to commandflags.

Special Keywords Available to Templates
---------------------------------------
project_name	This contains the name of the project.
project_file	This contains the name of the output file.
guid		This is used by the VC7 project and workspace creator.
configurations	When used within a foreach context, this info (each
		configuration) is gathered for use with the VC7 workspace
		creator.
flag_overrides  Used to determine flags that have been overridden on a per
                file basis.
custom_types    The list of custom file types that may have been defined
                in the mpc file or a base project.

Defaulting Behavior
-------------------
1) If a project name is not specified

   it will be defaulted to the name of the mpc file without the extension

2) If a particular list is not specified (Source_Files, Header_Files, etc.)

   all of the files in the directory will be added to the corresponding list
   by extension

3) If idl files exist in the directory and
   the IDL_Files components are left defaulted (i.e. not listed) and
   none of the idl generated files are listed in the corresponding lists

   the project is assumed to be a TAO project, the idl files are added to
   the IDL_Files list  and all of the (would be) generated files will be
   added to the front of the corresponding lists (source, inline and
   header lists)

4) If files are listed in the Source_Files list and
   a corresponding header or inline file exists

   the corresponding file will be added to the corresponding list (if it
   isn't already there)

5) If a sharedname is specified and staticname is not

   staticname is assigned the sharedname value (the same applies if
   staticname is specified and sharedname is not)

6) If pch_header is not specified and a header file matches *_pch.h

   it is assumed to be the precompiled header file (the same applies to
   pch_source)

7) If -relative is not used to set ACE_ROOT and the ACE_ROOT environment
   variable is set

   it will be used to set the relative value for ACE_ROOT.  If -relative is
   not used to set TAO_ROOT, it will be set from the TAO_ROOT environment
   variable.  If that is not set, the relative value of ACE_ROOT plus /TAO.

Processing Order
----------------
1) Project file is read
2) Template input file is read
3) Template file is read
4) Output project is written