ChangeLogTag: Wed Jul 26 22:35:28 UTC 2006 Chad Elliott <elliott_c@ociweb.com>

1 files changed, 297 insertions, 0 deletions

diff --git a/docs/USAGE b/docs/USAGE
new file mode 100644
index 00000000..eee85d4c
--- /dev/null
+++ b/docs/USAGE
@@ -0,0 +1,297 @@
+Running the Workspace Generator
+-------------------------------
+
+The most common way to use the Make Project Creator is to run the
+workspace generator (mwc.pl).  This script will generate projects and a
+single workspace that contains the generated projects.  If no input file
+(.mwc file) is specified, it will recurse into the directory in which the
+script was started.  It looks for .mpc files and generates a project or
+projects for each one found.
+
+
+Usage: mwc.pl [-global <file>] [-include <directory>] [-recurse]
+              [-ti <dll | lib | dll_exe | lib_exe>:<file>] [-hierarchy]
+              [-template <file>] [-relative NAME=VAR] [-base <project>]
+              [-noreldefs] [-notoplevel] [-static] [-genins] [-use_env]
+              [-value_template <NAME+=VAL | NAME=VAL | NAME-=VAL>]
+              [-value_project <NAME+=VAL | NAME=VAL | NAME-=VAL>]
+              [-make_coexistence] [-feature_file <file name>]
+              [-expand_vars] [-features <feature definitions>] [-gendot]
+              [-exclude <directories>] [-name_modifier <pattern>]
+              [-apply_project] [-version] [-into <directory>]
+              [-gfeature_file <file name>]
+              [-language <cplusplus | csharp | java | vb>]
+              [-type <automake | bds | bmake | em3 | ghs | html |
+                      make | nmake | sle | vc6 | vc7 | vc71 |
+                      vc8>]
+              [files]
+
+       -base           Add <project> as a base project to each generated
+                       project file.  Do not provide a file extension, the
+                       .mpb extension will be tried first; if that fails the
+                       .mpc extension will be tried.
+       -exclude        Use this option to exclude directories when searching
+                       for input files.
+       -expand_vars    Perform direct expansion, instead of performing relative
+                       replacement with either -use_env or -relative options.
+       -feature_file   Specifies the feature file to read before processing.
+                       The default feature file is default.features under the
+                       config directory.
+       -features       Specifies the feature list to set before processing.
+       -gendot         Generate .dot files for use with Graphvis.
+       -genins         Generate .ins files for use with prj_install.pl.
+       -gfeature_file  Specifies the global feature file.  The
+                       default value is global.features under the
+                       config directory.
+       -global         Specifies the global input file.  Values stored
+                       within this file are applied to all projects.
+       -hierarchy      Generate a workspace in a hierarchical fashion.
+       -include        Specifies a directory to search when looking for base
+                       projects, template input files and templates.  This
+                       option can be used multiple times to add directories.
+       -into           Place all output files in a mirrored directory
+                       structure starting at <directory>.
+       -language       Specify the language preference; possible values are
+                       [cplusplus csharp java vb].  The default is
+                       cplusplus.
+       -make_coexistence If multiple 'make' based project types are
+                       generated, they will be named such that they can coexist.
+       -name_modifier  Modify output names.  The pattern passed to this
+                       parameter will have the '*' portion replaced with the
+                       actual output name.  Ex. *_Static
+       -apply_project  When used in conjunction with -name_modifier, it applies
+                       the name modifier to the project name also.
+       -noreldefs      Do not try to generate default relative definitions.
+       -notoplevel     Do not generate the top level target file.  Files
+                       are still process, but no top level file is created.
+       -recurse        Recurse from the current directory and generate from
+                       all found input files.
+       -relative       Any $() variable in an mpc file that is matched to NAME
+                       is replaced by VAR only if VAR can be made into a
+                       relative path based on the current working directory.
+       -static         Specifies that only static projects will be generated.
+                       By default, only dynamic projects are generated.
+       -ti             Specifies the template input file (with no extension)
+                       for the specific type (ex. -ti dll_exe:vc8exe).
+       -template       Specifies the template name (with no extension).
+       -type           Specifies the type of project file to generate.  This
+                       option can be used multiple times to generate multiple
+                       types.  If -type is not used, it defaults to 'make'.
+       -use_env        Use environment variables for all uses of $() instead
+                       of the relative replacement values.
+       -value_project  This option allows modification of a project variable
+                       assignment .  Use += to add VAL to the NAME's value.
+                       Use -= to subtract and = to override the value.
+                       This can be used to introduce new name value pairs to
+                       a project.  However, it must be a valid project
+                       assignment.
+       -value_template This option allows modification of a template input
+                       name value pair.  Use += to add VAL to the NAME's
+                       value.  Use -= to subtract and = to override the value.
+       -version        Print the MPC version and exit.
+
+The default global input file (config/global.mpb) is used if -global
+is not specified on the command line.
+
+Two include directories are used by default (config and templates).
+
+Each project creator has a default template input file for each type of
+project (dll_exe, lib_exe, dll, lib).  You can override the default template
+input file name with the -ti option.  The file must have a 'mpt' extension
+and must reside within the include search directories.  NOTE: the 'lib' and
+the 'lib_exe' template input files are only used if the project creator makes
+a separate project file for dynamic libraries and static libraries.
+
+The -exclude option is used to exclude directories when searching for input
+files.  NOTE: This option has no effect when used with mpc.pl.
+
+The -gendot option (useful only to mwc.pl) will result in the generation of
+.dot files for each workspace processed.  Each .dot file will contain
+information that can be fed to Graphvis to display the dependency
+information for the various projects found within the workspace.
+
+The -genins option will cause MPC to generate an "install" file after
+processing each project that can be used in conjunction with the
+prj_install.pl script to install different parts of the project (such as
+header files) into an alternate location.
+
+The -hierarchy option is used to force the generation of a hierarchical
+workspace at each directory level in between the toplevel directory and the
+location of the mpc file that is being processed.  This is the default for
+"make" based workspace creators.  NOTE: This option only has an effect when
+passed to mwc.pl.
+
+The -template option is used to override the default template name.  This
+file should have a .mpd extension and sit in one of the include search
+directories.  NOTE: The -template option overrides the template file for all
+types specified.
+
+The -static option can be used to generate only static project files.
+
+The -static_only option has been replaced by the -static option.  Currently,
+MPC only supports generating dynamic projects or static projects, but not
+both during the same run.  To generate them both you must run MPC twice, once
+with the -static option and once without.  Additionally, the vc6, em3, vc7,
+vc71 and vc8 project names will no longer automatically have _Static
+appended to the project name when generating static projects.  This can
+still be achieved by using the -name_modifier option.
+
+When generating static projects, inter-project dependencies will not be
+generated for libraries within vc6, em3, vc7, vc71 workspaces.  The
+reason is due to the fact that each static library that depended upon another
+would be combined at the library creation stage, resulting in extremely large
+libraries.  Dependencies are handled correctly by vc8.
+
+This behavior can be modified by setting the
+MPC_DEPENDENCY_COMBINED_STATIC_LIBRARY environment variable.  It will force
+MPC to generate inter-project dependencies for libraries within a single
+workspace.
+
+The -name_modifier option can be used to modify the generated workspace or
+project name.  The parameter to the -name_modifier option is a pattern where
+an asterisk (*) within the pattern is replaced by the actual workspace or
+project name.  Thus, passing -name_modifier '*_Static' to mwc.pl will result
+in all workspace and project names ending in _Static. (Ex. FOO_Static.dsw,
+FOO_Static.dsp, etc.)
+
+The -apply_project option, when used in conjunction with the -name_modifier
+option, causes MPC to apply the name modifier to the project name in
+addition to the workspace and project file names.  This option has no effect
+outside the scope of the -name_modifier option.
+
+The -noreldefs option says not to generate default relative definitions for
+*_ROOT (which comes from environment variables).
+
+The -notoplevel option tells mwc.pl to generate all projects for a
+workspace, but do not generate the top level workspace file.  For mpc.pl, it
+says process the mpc files, but do not generate the project files.
+
+The -recurse option is used to search for all files that could be processed
+from the current directory and its sub-directories.  If directories are
+passed in a comma separated list (e.g -recurse=examples,apps,TAO), then
+those directories will be excluded when searching for project or workspace
+files.
+
+The -type option can be used multiple times on the same command line to
+generate projects of different types per mpc file.  The default type for
+this version of MPC is 'make'.  NOTE: The -ti option overrides the template
+input file for all types specified.
+
+The -feature_file specifies a file to be read that enables or disables
+features.  These feature names can be anything, but they should correspond
+to values used for the 'requires' and 'avoids' keywords.  If a feature is
+required and is not enable then the project will not be created.  If a
+feature is to be avoided and it is enabled then the project will not be
+created.
+
+The -features specifies additional list of features values. Values
+specified by this option overwrite values from features files.
+Example:
+mwc.pl -features "qos=1,ssl=0" ace.mwc
+
+The -value_template option can be used to set various template variables.
+If a template variable value will contain spaces, it is best to enclose the
+whole setting in double quotes and use single quotes within the value to
+retain spaces (if it is necessary).  Below is an example where the value
+will have spaces and some spaces need to be retained.
+
+mwc.pl -value_template "configurations=Debug Release 'Memcheck Debug' 'Memcheck Release'"
+
+
+Running only the Project Generator
+----------------------------------
+
+Most of what is stated about the Workspace Generator applies to the Project
+Generator except that it only generates projects.  If an input file (.mpc
+file) is not provided, the project creator will attempt to create a default
+project in the directory from which the script was started.
+
+
+MPC Codebase Configuration File
+-------------------------------
+This configuration file can be used to specify alternate locations for the
+MPC Configuration File.  If a base.cfg is found underneath the 'config'
+directory where MPC is executed, it will be read to determine the location
+of MPC.cfg based on the directory in which MPC was started.
+
+For example, if $MPC_ROOT/mwc.pl is run under /foo/bar_root/src and
+$MPC_ROOT/config/codebase.cfg contained:
+
+/foo/bar_root = /foo/bar_root/MPC/config
+
+MPC would attempt to open and read /foo/bar_root/MPC/config/MPC.cfg as the
+MPC Configuration File.  If the codebase configuration file is not present,
+MPC will try to use $MPC_ROOT/config/MPC.cfg as the MPC Configuration File.
+
+
+MPC Configuration File
+----------------------
+In an effort to move away from the use of environment variables, a
+configuration file has been introduced.  The configuration file (MPC.cfg)
+can contain settings to provide command line options, control logging and
+direct MPC to dynamic project types.
+
+The following keywords are allowed in the configuration file, which will be
+read from the 'config' directory of MPC.
+
+command_line     - Provide additional command line options to MPC.  The
+                   value of this setting will be prepended to the options
+                   passed to mwc.pl or mpc.pl.
+dynamic_types    - This comma separated list points to directories in which
+                   MPC will search for Perl modules to implement additional
+                   MPC project types, base projects or template files.  This
+                   setting can be used to augment or replace functionality
+                   in MPC.  For each suitable directory found, it will add a
+                   'modules' include path for Perl to find modules, add a
+                   'config' include path to locate base projects and a
+                   'template' include path to find MPC templates.
+includes         - Similar to the -include command line option, it adds the
+                   list of comma separated paths to the MPC include search
+                   paths.
+logging          - If this setting contains info=1, informational messages
+                   will be printed.  If it contains warn=1, warning messages
+                   will be printed.  If it contains diag=1, diagnostic
+                   messages will be printed.  And lastly, if it contains
+                   detail=1, detail messages will be printed.  If it
+                   contains none of these, MPC will not print out any
+                   information or warnings when processing projects or
+                   workspaces.  Errors are always printed if any are
+                   encountered.
+verbose_ordering - If this is set, mwc.pl will warn the user about
+                   references to projects in the 'after' keyword that have
+                   not been processed.
+
+Below is an example configuration file:
+
+// MPC configuration file
+dynamic_types = /builds/ACE_wrappers/bin/MakeProjectCreator
+logging = info=1 warn=1
+verbose_ordering = 1
+
+
+Environment Variables
+---------------------
+
+MPC_DEPENDENCY_COMBINED_STATIC_LIBRARY - See the -static section above.
+
+The following environment variables are deprecated
+and will be removed in a future version of MPC
+--------------------------------------------------
+
+MPC_COMMANDLINE - The value of this environment variable will be prepended
+to the options passed to mwc.pl or mpc.pl (if any are passed).
+
+MPC_VERBOSE_ORDERING - If this is set, mwc.pl will warn the user about
+references to projects in the 'after' keyword that have not been processed.
+
+MPC_SILENT - If this is set, MPC will not print out any information or
+warnings when processing projects or workspaces.  Errors are always printed
+if any are encountered.
+
+MPC_LOGGING - If this is set, MPC will parse the value and provide
+informational, warning, diagnostic and detail messages depending on it's
+setting.  If the MPC_LOGGING value contains info=1, informational messages
+will be printed.  If it contains warn=1, warning messages will be printed.
+If it contains diag=1, diagnostic messages will be printed.
+And lastly, if it contains detail=1, detail messages will be printed.  If it
+contains none of these, MPC will act as if MPC_SILENT was set.