Building components with abld
tools.abld
this chapter documents abld to e32toolp release 210 level.
Overview
The abld tool can be used to control the building of components which have been defined by a bldmake component description file.  Once the bldmake bldfiles command has been executed for your component, abld can be used to carry out the various stages involved in building the component. 
Abld Invocation syntax
abld [ test ]  command  [ options ]  [ platform  [ build  [ program ] ] ]
command :
	build
clean
export
final
freeze
help
library
listing
makefile
reallyclean
resource
target
tidy
options :
	-check|-c
	-keepgoing|-k
	-savespace|-s
	-verbose|-v
	-what|-w
bldmake bldfiles creates a file called ”Abld.bat” in the current directory.  When invoked, this file runs Perl on the script \EPOC32\Tools\Abld.pl, passing the location of the files that bldmake bldfiles has generated for use with abld. abld processes it’s command line and constructs a corresponding list of NMAKE.EXE calls to be made to the makefiles which bldmake has generated for the component. abld then makes each of the NMAKE.EXE calls in turn, having changed directory to that containing the relevant bld.inf file.
Where “test” is specified before command, the command will operate on all the projects defined by mmp files listed in the prj_testmmpfiles section of the component description file, rather than those projects defined by mmp files listed in the prj_mmpfiles section.  Note that the “test” parameter is irrelevant for some commands and, in those cases, cannot be specified.
If platform is not specified, or is specified as “ALL”, then abld will carry out the specified command for all the platforms specified in the component description file.  Where build can be specified as a parameter to a particular command, if it is unspecified or specified as “ALL”, abld will carry out the specified command for builds “UDEB” then “UREL”.  Specify the basename of the relevant mmp file or extension makefile for the program parameter to limit the command to a single project within a component.  Where program is unspecified, the specified command will be carried out for all projects within the component.
Note that, for certain abld commands, not all the parameters - platform, build and program - apply.
Note also that not all the options apply for all the commands, and that, where they do apply, they can be specified in either their long or abbreviated forms.
Abld build
This command combines the effects of several abld commands in one, and will probably be all you’ll need to invoke to build your component.
abld [ test ] build ( ( [-c] | [-w] ) | ( [-s] [-k] [-v] ) )  [ platform ] [ build [ program ] ]
The abld commands that this command combines are EXPORT, MAKEFILE, LIBRARY, RESOURCE, TARGET and FINAL, which are carried out in turn.
Abld clean
This command will erase all the files created by the corresponding abld target command.
Abld [ test ] clean ( ( [-c] | [-w] ) | ( [-k] [-v] ) ) [ platform ] [ build [ program ] ]
abld clean makes use of the CLEAN targets provided in makefiles generated by makmake.  The files that are removed by this command include all the intermediate files created during compilation and all the executables and import libraries created by the linker.
Abld export
This command copies all the files to be exported from source to their destinations, as defined in the prj_exports or prj_testexports section of the component description file depending upon whether the test parameter is specified or not.
Abld [ test ] export ( ( [-c] | [-w] ) | ( [-k] [-v] ) ) 
Each destination file is only created if it does not exist or has an earlier datestamp than the corresponding source file.  The directories which will contain the destination files will be created automatically if they do not exist.
Abld final
This command allows extension makefiles to be used to carry out any commands required to complete the build.
Abld [ test ] final [-k] [-v] [ platform ] [ build [ program ] ]
The command has no effect for makefiles generated by makmake, only for extension makefiles.
Abld freeze
This command freezes new DLL exports in frozen .def files using the FREEZE target provided in makefiles generated by makmake.
Abld [ test ] freeze [-k] [-v] [ platform ] [ program ] 
The frozen def files should be considered part of source for your component.
To freeze your component for the first time, having built the component, call this command.  Next, regenerate the makefiles so that import libraries can be created from the frozen def files.  The import libraries can be created explicitly using the abld library command, or they can be built implicitly via abld build or abld target.
To add new exports to a project within your component, having built the component, call this command.  Next, rebuild the import libraries so that they incorporate the new exports.
Abld help
This command provides a brief guide to abld command-line syntax.
Abld help ( ( [ options ] | [ commands ] ) | ( command ) )
abld help options lists the options available with abld, while abld help commands lists the available commands.
abld help command displays the syntax for a particular command and also a brief description of what the command is for.
Abld library
This command creates the import libraries for the DLLs in your component by calling the LIBRARY target provided in makefiles generated by makmake.
Abld [ test ] library [-k] [-v] [ platform ] [ program ] 
Import libraries are generated directly from frozen def files, so exported functions will not be incorporated into import libraries until these functions are frozen with abld freeze.
The import libraries are created implicitly as part of the build activity carried out by abld target (and thus abld build), so it isn’t generally necessary to call this command separately if projects are listed in the component description file in order of dependency - dependent projects appearing after those projects they depend upon.  If ther are mutual imports between projects within your component then abld library can be called explicitly, though mutual imports are often a sign of poor software design.
An import library will not be regenerated if it has a later datestamp than the corresponding frozen def file.
Abld listing
This command creates an assembler listing file for a particular source file.
Abld [ test ] library [-k] [-v] [ platform ] [ build ] [ program ] [ source_basename ]
The listing file has same basename as the source code file with the extension .lis.  The listing file is created in the build directory and then copied to the directory containing the source file.  This command is only currently supported for ARM platforms.
Abld makefile
This command creates the makefiles for each project within your component, via makmake.
Abld [ test ] makefile ( ( [-c] | [-w] ) | ( [-k] [-v] ) ) [ platform ] [ program ] 
To generate the makefiles, makmake is invoked with the -d switch, which causes the makefiles to be created in a subdirectory of directory \EPOC32\Make\.  The makefiles are always created with this command, regardless of whether the corresponding mmp files have been changed or not.
Abld reallyclean
This command does what abld clean does, and also removes files exported by abld export and the makefiles generated by abld makefile.
abld [ test ] reallyclean ( ( [-c] | [-w] ) | ( [-k] [-v] ) ) [ platform ] [ build [ program ]] 
Abld resource
This command builds the resource files, bitmaps and application information files for a component by calling the RESOURCE targets in makefiles generated by makmake.
abld [ test ] resource [-k] [-v]  [ platform ] [ build [ program ] ]
These “resources” are created implicitly when abld target (and thus, abld build) is called.  The resources will not be regenerated if they have later datestamps than their source dependencies.
Abld target
This command builds the executables for your component.
abld [ test ] target ( ( [-c] | [-w] ) | ( [-s] [-k] [-v] ) )  [ platform ] [ build [ program ] ]
Since, in the makefiles generated by makmake, the main target is dependent upon the RESOURCE and LIBRARY targets, resources and import libraries will also be created when the main target is built. .  Executables will not be regenerated where they have later datestamps than the source files they depend upon.
Abld tidy
This command removes releasables defined by .mmp files which are listed with the “tidy” attribute in your component’s description file.
Abld [ test ] final [-k] [-v] [ platform ] [ build [ program ] ]
The command can be run following a build to remove any releasables which are no longer required now that the build has completed.
Option: abld -check
This option is for checking that the required files have been created during a particular build step.  The option creates a list of files that should have been created and then checks that each one exists in turn.  If a file is missing the full name of the file is piped to STDERR.
Note that if this option is specified with abld build, makefiles will not be included in the list of files to be checked.  If the option is specified with abld reallyclean, however, the makefiles will be included in the list.
Option: abld -keepgoing
This option tells a particular abld command to “keep going” even if unrelated build steps report errors.
Option: abld -savespace
This option removes intermediate files created during the building of a project if the build is eventually successful.  If the build fails, the intermediate files remain so that errors can be corrected and an incremental rebuild of the project version that failed to build can take place.
Option: abld -verbose
This option pipes to STDOUT the calls to tools that a particular build step is making, and can be useful in determining exactly where an error occurs during the build process.
Option: abld -what
This option creates a list of files in exactly the same way as option -check.  The list of files is then piped to STDOUT.
The option could be useful to find out where a particular build step is creating files, or for creating a zip file containing the releasables for a component by piping the list of files to a file and then having a zip utility process this file.