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 [, ... ]])
Specifies multiple "sub targets" to be built. Please see the full documentation.

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 [, ...]] )
Adds header file include paths to the project. See also AddModuleIncludes().

project.RemoveIncludes( source1_path:string [, source2_path [, ...]] )
Removes header file include paths from the project. See also RemoveModuleIncludes().

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 [, ...]] )
Removes header file include paths from the project. See also RemoveIncludes().

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 $