Building Derelict

Introduction

There are some wonderful build tools created by D users, such as Bud and Rebuild. Given a single source module, these tools are able to parse all of the modules imported by your application and cause them to be compiled and linked into the final executable. This is the recommended way to use Derelict. Unfortunately, it is not always possible.

There are times when you may need to compile the Derelict packages into static libraries. An example is when using an IDE that has a two-step compile and link process. In such cases, D support is usually an extension and the IDE is not aware of tools like Bud and Rebuild. One such IDE is Code::Blocks. If you find yourself needing to use Derelict in library form, a build script is included in the top-level Derelict directory ($DERELICT_HOME). buildme.d can be used to compile all of the Derelict packages or only those you specify. How to do so is detailed below.

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 packages have built-in support for Tango. However, currently the the install script is not configured for Tango and will not execute in a Tango environment. When you execute the script, make sure you do so in a Phobos environment.

The Build Script

Currently, the build script requires that Bud be on your PATH. If it is not, the script will fail execution. In the future, support for Rebuild will be added. How you execute the build script depends upon the environment you have configured (Phobos or Tango) and which tools you decide to use. Following are descriptions for different ways to use the build script, two of which require compilation and only one of which will currently work in a Tango environment.

Execution as a Script

In a Phobos environment you can execute buildme.d as a script, without compiling it first, using 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, anytime you see 'dmd' in a command line, you can replace it with 'gdmd' to use the same command line with GDC. You can also compile the script with DMD or GDC, but then you'll need to clean up the output files.

Compiling with Bud

The build script uses Bud to compile Derelict packages into static libraries. You can also use Bud to compile the build script into an executable. This is not really necessary, nor is it really recommended. But, the option exists as long as you are in a Phobos environment. For some reason, Bud can compile the Derelict packages just fine in a Tango environment, but fails to compile buildme.d. The following is the recommended command line:

    bud -clean buildme.d

Passing the -clean option to Bud will cause all temporary output files to be deleted once the process completes. You can then execute buildme like any other executable.

Compiling with Rebuild

This option is the only one of the three listed here that works in a Tango environment, but it also works in a Phobos environment. The command line is very similar to that for Bud above:

    rebuild -clean buildme.d

The -clean option will cause most of the temporary output files to be deleted. But Rebuild currently does not delete MAP files generated by DMD on Windows, so you will have a buildme.map lying around in the directory after execution.

Options

Whether you run buildme.d as a script or compile it into an executable, you first 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

Or, for the compiled form:

    buildme debug

The script also accepts 'release' as a command line argument.

The build script generates a temporary build 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

Or for the compiled form:

    buildme 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

Or for the compiled form:

    cd $DERELICT_HOME
    buildme 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

Or for the compiled form:

    cd $DERELICT_HOME
    buildme cleanlib

This will delete the libraries in $(DERELICT_HOME/lib). Unlike the other command line options, this option is exclusive to other options. If any options precede it, it will be ignored. Likewise, any options following 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.