Building Derelict



Introduction

While it is possible to compile any or all of the Derelict packages into static libraries, it is not recommended that you do so. The provided build script exists solely as a convenience for those who absolutely need it. The recommended way of using Derelict in your applications is to make use of a build tool, such as Bud or Rebuild. Given a single D source module, these tools can automatically compile and link all imported modules to create an executable. So unless you absolutely must use the static libraries, please consider using the recommended approach instead.

For those who do need the libraries, in the top-level Derelict directory ($DERELICT_HOME) you will find a D module named buildme.d. It can be, and is intended to be, run as a script. Executing this file will create one or more libraries from the Derelict packages. At the end of execution, all of the libraries that were created will be found in the $DERELICT_HOME/lib directory.

Setting Up An Import Directory

Whether you run the build script or not, when you compile applications using Derelict you need to let the compiler know where it can find the Derelict source modules. The directory tree of the Derelict distribution is designed to for ease of maintenance. Each package is clearly segregated into its own directory. Because of this structure, when compiling a Derelict application you have to pass the path to each package you use to the compiler. For example, if building an app using DerelictSDL and DerelictGL, you need to do something like this:
bud myapp.d -IDerelictDir/DerelictGL -IDerelictDir/DerelictSDL -IDerelictDir/DerelictUtil
When using response files, this is a non-issue. However, many people prefer to have all of their D modules in a single import tree. For a long time, Derelict users who wanted such a setup had to copy the Derelict modules to their import tree manually, or use a custom script. As a result, Derelict now includes a very basic install script written in D. Given a root directory, this script will create a subdirectory 'derelict' and copy all derelict modules into that tree. Then you can add all of the to the import path with a single command line switch, '-IRootDir'. The following command line will execute the install script (if you are using GDC, replace 'dmd' with 'gdmd':
    dmd -run install.d RootDir
'RootDir' is a required argument and should be the complete path to the directory in which you want to install the Derelict modules. Note that this does not copy any Derelict libraries (remember, you do not need to build the Derelict libraries if you use a build tool like Bud or Rebuild to compile your D apps). This simple script is provided as a convenience. While I will certainly respond to bug reports, I make no promises about enhancing its functionality.
Derelict has built-in support for Tango. However, currently the neither the install script nor the build script (described below) can be executed in a Tango-enabled environment. If you need to use Derelict with Tango, you must do so using the method recommended above (with Bud or Rebuild).

TheBuild Script

Currently, the build script requires that Bud be on your PATH. If it is not, the script will fail. To execute the build script, cd to $DERELICT_HOME and use one of the following command lines:
    dmd -run buildme.d
    gdmd -run buildme.d
The first is the command line to use with DMD. The second is for GDC. In the rest of this document, 'dmd' will be used for all example command lines. Anytime you see 'dmd', you can replace it with 'gdmd' to use the same command line with GDC.

Options

Before executing the build script, you need to decide which libraries you want to build and how you want to build them. There are a few command line options you can pass along. With the exception of the 'cleanlib' option, all options may be passed in any order. By default, each package will be built in Release mode. You can specify debug mode by passing 'debug' on the command line:
    dmd -run buildme.d debug
The script also accepts 'release' as a command line argument. The build script generates a temporary Bud Response File that is deleted at the end of execution. Sometimes, when debugging problems with the build script, it is necessary to see the contents of this file. You can prevent the script from deleting the file by passing 'nodelbrf' on the command line:
    dmd -run buildme.d nodelbrf
You can also pass options to both Bud and the compiler, though not via the command line. This is done through the following three options files:
$(DERELICT_HOME)/buildopts/bud_common.txt
$(DERELICT_HOME)/buildopts/bud_release.txt
$(DERELICT_HOME)/buildopts/bud_debug.txt
Options in bud_common.txt are used in both Debug and Release builds. The other two are self-explanatory.

The rules for editing these files are the same as those for editing Bud Response Files, but there are some caveats. Because buildme.d automates the build process, some assumptions are made. The first is that the output directory will be the $DERELICT_HOME/lib subdirectory. Adding -TsomeDir to any of the three files will have no effect. Second, the import paths for building each package are set automatically so that you don't need to. Third, the DerelictUtil package and other dependencies are excluded from the compilation automatically via the -X Bud option (except, of course, when DerelictUtil itself is being compiled).

For most users, the default configuration should suffice.

Which Packages?

If you only want to build one or more specific packages, rather than all of them, you can specify the package names on the command line:
    cd $DERELICT_HOME
    dmd -run buildme.d DerelictAL DerelictUtil
The above will build only the DerelictAL and DerelictUtil libraries.

Cleaning Up

During compilation, all object files will be deleted by the script. If you want to delete all of the libraries, you can do so with the following command:
    cd $DERELICT_HOME
    dmd -run buildme.d cleanlib
This will delete the libraries in $(DERELICT_HOME/lib). Unlike the other command line options, this option must be specified first. Any options following it will be ignored. If it is not first, it will be ignored.

Troubleshooting

If you have any problems building Derelict with Bud, you may direct them to the Derelict Forums and someone will try to help you. Please don't post problems on the Bud forums unless you are absolutely certain the problem is with Bud and not with Derelict.