Umake API
Ribosome v2.4
This API documentation covers the current version of Ribosome's umake
tool. Methods marked with a version specify what minimum version of
Ribosome is required to get that feature. Methods without any version
were available in v2.3. Deprecation warnings are also listed for those
items that are scheduled for removal.
Versioning
UmakefileVersion( major:integer , minor:integer )
All umake files should start with a call to
UmakefileVersion(),
this will tell the build system how to interpret the contents
of the umake file in a way that is backwards compatible.
When creating a new umake file, you should use the version
of the build system you are currently using. This documentation
was written for build 2.2 which means that you should use
UmakefileVersion(2,2) in order to get the
build system to behave as described here.
Targets
DLLTarget( target:string [ , libtarget:string ] )
Specifies a dynamic library should be built from the project
data, with output name
target. Umake may add
a platform-appropriate extension to the output name, and change the
name to include versioning information. There are also several other
methods of changing the output name of the DLL.
If the optional argument libtarget is
specified, the *.lib file generated by some platforms will use this
name instead of target.
DLLWithResourceTarget( target:string , rtarget:string , rfile:string ,
includes:list )
On the Macintosh OS9, this builds a DLL and Windows .xrs DLL.
On all other platforms, this method simply calls
DLLTarget( target ).
EmptyTarget()
Creates a Makefile with no targets.
LibraryTarget( target:string )
Specifies a static library should be built from the project
data, with name target. Umake may add a
platform-appropriate extension to the output name. There are no other
ways of changing the output name for a static library, and
target must be the same as the CVS module
name.
MultiTargetMake( umakefil1_path:string [ , umakefil2_path:string
[, ... ]])
NonObjectTarget( target:string )
version 2.4
Specifies that some target file is going to be built from the project
data, using only a compiler. No linker will be applied to this project.
Target name should be an exact match for what the expected output name
is (the name does not get processed as it does in other target calls).
ProgramTarget( target:string )
Specifies a executable should be built from the project data,
with name name target. Umake may add a
platform-appropriate extension to the output name.
ProgramWithResourceTarget( target:string , rtarget:string ,
rfile:string , includes:list )
On the Macintosh OS9, this builds a program and Windows .xrs
DLL. On all other platforms, this method simply calls
ProgramTarget( target )
.
Other Methods
addLibpaths( string:libpath ... )
This method lets you add paths to be added to the LIBPATH= line in
the Makefile. Useful in conjunction with SDKPath methods to automate
the building of library paths. Win32 only.
getLibpaths() : string
This method returns a string of the libpaths you have added using
addLibpaths().
GetSDKPath( string:sdk_name ) : string
This function allows you to access the path to an third party library
or SDK. These paths should be defined in your
buildrc file, or using environment
variables. For more information on sdk's, see
the SDK BIF tag.
GetSDKPath() will always
return an absolute path.
removeLibpaths( string:libpath ... )
This method lets you remove libpaths that have been previously added
using
addLibpaths().
SetSDKPath( sdk_name:string , path:string )
This function tells the build system where to find an SDK.
It is required in order for the build system to be able to
find directx and other third party libraries. These paths
can later be used in your
umake files
and should also be declared in your
BIF
files.
Methods of Project
A word on project data
Currently, project is a global object that represents the data for the
current umake target. There are many many methods, and many attributes
within this object that have been presented and are directly accessible.
This leads to some pretty ugly coupling and difficult paths to umake
enhancement. At some point in the future, this style of accessing
project data and methods directly is going to go away completely in
favor of a more clearly defined (and hopefully simpler) umake API.
project.SetDLLTypePlugin()
project.SetDLLTypeCodec()
project.SetDLLTypeCommon()
Specifies the DLL being built is a G2 plug-in, codec, or
common(normal). This is used when building in a mode which
statically links the plug-ins into the player.
project.AddBuildOption( option:string )
Sets the same type of build option as the -t option does on the
command line. Results may be mixed, because a particular option may
have to be processed before the Umakefil is executed.
project.RemoveBuildOption( option:string )
Removes a build option if it was previously set. Results may be
mixed, because a particular option may have already been processed
before the Umakefil is executed.
project.BuildOption( option:string ) : boolean
Checks if a build option was set.
project.AddSources( source1_path:string [, source2_path:string
[, ...]] )
Adds sources to the project. This method takes a comma-separated list
of strings. Use UNIX-style (/) path separators on all platforms;
Umake will convert these paths to the platform-specific paths
automatically.
project.AddModuleSources( source1_path:string [, source2_path:string
[, ...]] )
Similar to AddSources, but each source is relative to the source root
rather than the current directory.
project.RemoveSources( source1_path:string [, source2_path:string
[, ...]] )
Removes sources already added to the project, while not blocking those
sources from being included later in the Umakefil. The paths must
match the string they were added with exactly.
project.AddSourceObjects( source1_path:string [, source2_path:string
[, ...]] )
Adds pre-compiled object files to the project. This feature is used in
the codes for hand-optimized assembly from Intel.
project.RemoveSourceObjects( source1_path:string [, source2_path:string
[, ...]] )
Removes pre-compiled object files from the project.
project.AddIncludes( source1_path:string [, source2_path:string
[, ...]] )
project.RemoveIncludes( source1_path:string [, source2_path
[, ...]] )
project.AddModuleIncludes( module1:string [, module2:string
[, ...]] )
Similar to
AddIncludes(), but paths should be
relative to the build root and always use "/" as path separators. So,
instead of doing:
project.AddIncludes("../gemctl/pub")
you can do:
project.AddModuleIncludes("gemctl/pub")
project.RemoveModuleIncludes( module1:string [, module2
[, ...]] )
project.AddDefines( define1:string [, define2
[, ...]] )
Adds C/C++ defines to the project. A define string without a string
assignment will default to true, otherwise a value can be set by
including the assignment in the string with a = sign. For
example:
project.AddDefines( "DEBUG=2" )
would add the following to the header file:
#define DEBUG 2
project.RemoveDefines( define1:string [, define2:string
[, ...]] )
Removes C/C++ defines from the project. They must appear exactly as
they were added.
project.IsDefined( define:string ) : boolean
Returns true if define is defined, false
otherwise.
project.AddLibraries( lib1_path:string [, lib2_path:string
[, ...]] )
project.RemoveLibraries( lib1_path:string [, lib2_path:string
[, ...]] )
project.AddSystemLibraries( lib1_path:string [, lib2_path:string
[, ...]] )
project.RemoveSystemLibraries( lib1_path:string [, lib2_path:string
[, ...]] )
project.AddDynamicLibraries( lib1_path:string [, lib2_path:string
[, ...]] )
project.RemoveDynamicLibraries( lib1_path:string [, lib2_path:string
[, ...]] )
project.AddModuleLibraries( lib1_path:string [, lib2_path:string
[, ...]] )
This method links against a library created by the build system.
Each argument should be the name of the module containing that library.
If the module is in a subdirectory, / can be used to specify the name.
If the name of the library is not the same as the directory it is in,
you can append [libname] to specify the name of the library.
Examples: (where "release" is sometimes replaced with "debug")
project.AddModuleLibrary("pnmisc") # Link against pnmisc/release/pnmisc.lib
project.AddModuleLibrary("foo/bar") # Link against foo/bar/release/bar.lib
project.AddModuleLibrary("foo/bar[gazonk]") # Link against foo/bar/release/gazonk.lib
When executing
AddModuleLibraries, umake will
also look for a file called
[module]/[libraryname]_linkhook.cf and execute it
if present. This allows the module to add include paths and other magic
so that the library users don't have to think about it.
Examples:
project.AddModuleLibrary("pnmisc") # Executes pnmisc/pnmisc_linkhook.cf
project.AddModuleLibrary("foo/bar") # Executes foo/bar/bar_linkhook.cf
project.AddModuleLibrary("foo/bar[gazonk]") # Executes foo/bar/gazonk_linkhook.cf
project.RemoveModuleLibraries( lib1_path:string [, lib2_path:string
[, ...]] )
project.AddLocalLibraries( lib1_path:string [, lib2_path:string
[, ...]] )
project.RemoveLocalLibraries( lib1_path:string [, lib2_path:string
[, ...]] )
project.AddSystemPaths( path1:string [, path2:string
[, ...]] )
project.RemoveSystemPaths( path1:string [, path2:string
[, ...]] )
project.ExportFunction( func:string , proto:string [, includedir,
includefile ] )
This function should be used in DLLs to export functions which
needs to be accessed from outside the DLL. The proto should
be a list of arguments accepted by this function. The proto
will be used to build prototypes for this function in global header
files. If the includeddir and includefile parameters
are present, the includefile will be added to the generated
header file, and includedir is the directory which contains
that include file. Includefile should be relative to the
source root as it will be sent to
project.AddModuleIncludes()
in the project which use this header file.
project.RemoveExportedFunctions( func1:string [, func2:string
[, ...]] )
project.AddCopyTargets( path1:string [, path2:string
[, ...]] )
project.RemoveCopyTargets( path1:string [, path2:string
[, ...]] )
project.SetModuleDepth( depth:integer )
This function tells the build system how many directory levels
below the build root this module is. The default value is 1.
project.EnableFeature( feature:string )
This function allows you to manually do what
UmakefileVersion() does.
This is the list of features you can turn on using this function:
- submodules
- This will enable multi-target umake files to cd into the
directory where a submodule is located instead of trying
to execute it from the current working directory.
versioning_off
This will turn off name mangling for DLLs on most platforms.
Normally *.ver files are used to create a versioned filename
for DLLs, but with this feature. (Which is on by default if
you use UmakeFileVersion(2,1) or greater)
project.AddDebugOutput( env_var:string , rel_path:string )
Warning: scheduled for deprecation in version 3.0
This function takes an environment variable and a relative
path as arguments. If the environment variable exists, a
link to/alias to/copy of the output will be placed in that
directory. Example:
project.AddDebugOutput("RP_DEBUG_BASEDIR","plugins/rv/")
This will copy the output into $RP_DEBUG_BASEDIR/plugins/rv/
Since the paths are often platform specific, this functions
should normally only be used in pcf files.
NOTA BENE:
The rel_path arguments *must* end with a slash if it
is a directory.
project.AddFileDependency( file:string , depend:string [, depend:string
[, ... ]] )
This will add a dependency to the generated makefile so that
make knows that file depends on depend.
project.SetDistLocation( [release=location:string]
, [debug=location:string] , [any=location:string] )
This will tell umake to check in the library/dll/program generated by
this umakefile into the location given by 'location'. The location
is relative to the source root and must be a directory which has a
<checkin_dependlist>
from this module.
The location should be given using one of the named parameters
release, debug or any.
If you use the release parameter, then the
checkin will only be performed if this is a release build.
The location can use brackets to specify the location and name of the
library, a few examples to illustrate. For simplicity, I will assume
that project.SetDistLocation was used in a LibraryTarget umakefile.
project.SetDistLocation(release="foo/bar[../gazonk]")
This will check in the library as 'gazonk'. It will be checked in
at the top level so that the distribution will be shared by both
debug and release builds using this dist. If this is a debug build,
then nothing will happen.
project.SetDistLocation(debug="foo/bar[./gazonk]")
This will check in the library as 'gazonk'. It will be checked in
into the debug directory of the foo/bar module, but only if this is a
debug build, otherwise nothing will happen.
project.SetDistLocation(any="foo/bar[./gazonk]")
This will check in the library as 'gazonk'. It will be checked in
into the release/debug directory depending on what kind of build
this is.
project.SetDistLocation("foo/bar")
This will check in the library as 'foo'.
It will search the foo/bar directory to see if the library
already exists, and if it does check it into the same place.
If it does not exist, it will be checked in into the
debug/release directory as approperiate. However, no checkin
will take place if this is a debug build.
Last Updated: $Id: umakefil.html,v 1.11 2006/06/19 23:11:26 jfinnecy Exp $