root/trunk/docs/build.html

Revision 265, 9.4 kB (checked in by aldacron, 1 year ago)

[General]
* incorporated larsivi's patch to buildme.d so that it now works in a Tango environment
[Docs]
* updated build.html to give reflect the build script changes and to clarify the different ways to build Derelict as well as the rationale
[DerelictGL]
* several of the function pointer declarations in arb/multitexture.d had the wrong signature
[DerelictILUT]
* was not compatible with Tango
[DerelictODE]
* was not compatible with Tango
* import statements now all have an explicit 'private' to be consistent with the rest of Derelict

  • Property svn:mime-type set to text/html
  • Property svn:mim-type set to text/html
Line 
1 <html lang="en">
2 <head>
3     <title>Building Derelict</title>
4     <link rel="stylesheet" type="text/css" href="styles.css">
5 </head>
6 <body>
7 <hr>
8 <hr>
9 <h2 align="center">Building Derelict</h2>
10 <hr>
11 <hr>
12 <h3>Introduction</h3>
13 There are some wonderful build tools created by D users, such as
14 <a href="http://www.dsource.org/projects/build">Bud</a> and
15 <a href="http://www.dsource.org/projects/dsss/wiki/Rebuild">Rebuild</a>. Given
16 a single source module, these tools are able to parse all of the modules imported
17 by your application and cause them to be compiled and linked into the final
18 executable. This is the recommended way to use Derelict. Unfortunately, it is not
19 always possible.
20 <p>
21 There are times when you may need to compile the Derelict packages into static
22 libraries. An example is when using an IDE that has a two-step compile and link
23 process. In such cases, D support is usually an extension and the IDE is not
24 aware of tools like Bud and Rebuild. One such IDE is
25 <a href="http://www.codeblocks.org/">Code::Blocks</a>. If you find yourself
26 needing to use Derelict in library form, a build script is included in the
27 top-level Derelict directory ($DERELICT_HOME). <tt>buildme.d</tt> can be used
28 to compile all of the Derelict packages or only those you specify. How to do
29 so is detailed below.
30 </p><p>
31
32 <h3>Setting Up An Import Directory</h3>
33 Whether you run the build script or not, when you compile applications using
34 Derelict you need to let the compiler know where it can find the Derelict source
35 modules. The directory tree of the Derelict distribution is designed to for ease
36 of maintenance. Each package is clearly segregated into its own directory. Because
37 of this structure, when compiling a Derelict application you have to pass the path
38 to each package you use to the compiler. For example, if building an app using
39 DerelictSDL and DerelictGL, you need to do something like this:
40
41 <pre>
42 bud myapp.d -IDerelictDir/DerelictGL -IDerelictDir/DerelictSDL -IDerelictDir/DerelictUtil
43 </pre>
44
45 When using response files, this is a non-issue. However, many people prefer to
46 have all of their D modules in a single import tree. For a long time, Derelict
47 users who wanted such a setup had to copy the Derelict modules to their import
48 tree manually, or use a custom script. As a result, Derelict now includes a very
49 basic install script written in D. Given a root directory, this script will
50 create a subdirectory 'derelict' and copy all derelict modules into that tree. Then
51 you can add all of the to the import path with a single command line switch,
52 '-IRootDir'.
53
54 The following command line will execute the install script (if  you are using
55 GDC, replace 'dmd' with 'gdmd':
56
57 <pre>
58     dmd -run install.d RootDir
59 </pre>
60
61 'RootDir' is a required argument and should be the complete path to the directory
62 in which you want to install the Derelict modules. Note that this does not copy
63 any Derelict libraries (remember, you do not need to build the Derelict libraries
64 if you use a build tool like Bud or Rebuild to compile your D apps).
65
66 This simple script is provided as a convenience. While I will certainly respond
67 to bug reports, I make no promises about enhancing its functionality.
68
69 <div class="important">Derelict packages have built-in support for
70 <a href="http://www.dsource.org/projects/tango">Tango</a>. However, currently the
71 the install script is not configured for Tango and will not execute in a Tango
72 environment. When you execute the script, make sure you do so in a Phobos environment.</div>
73
74 <h3>The Build Script</h3>
75
76 Currently, the build script requires that <a href="http://www.dsource.org/projects/build">
77 Bud</a> be on your PATH. If it is not, the script will fail execution. In the future, support
78 for Rebuild will be added. How you execute the build script depends upon the environment
79 you have configured (Phobos or Tango) and which tools you decide to use. Following are
80 descriptions for different ways to use the build script, two of which require
81 compilation and only one of which will currently work in a Tango environment.
82
83 <h4>Execution as a Script</h4>
84
85 In a Phobos environment you can execute <tt>buildme.d</tt> as a script, without
86 compiling it first, using one of the following command lines:
87
88 <pre>
89     dmd -run buildme.d
90     gdmd -run buildme.d
91 </pre>
92
93 The first is the command line to use with DMD. The second is for GDC. In the rest
94 of this document, anytime you see 'dmd' in a command line, you can replace it with
95 'gdmd' to use the same command line with GDC. You can also compile the script with
96 DMD or GDC, but then you'll need to clean up the output files.
97
98 <h4>Compiling with Bud</h4>
99
100 The build script uses Bud to compile Derelict packages into static libraries. You can
101 also use Bud to compile the build script into an executable. This is not really
102 necessary, nor is it really recommended. But, the option exists as long as you are
103 in a Phobos environment. For some reason, Bud can compile the Derelict packages
104 just fine in a Tango environment, but fails to compile <tt>buildme.d</tt>. The
105 following is the recommended command line:
106
107 <pre>
108     bud -clean buildme.d
109 </pre>
110
111 Passing the <tt>-clean</tt> option to Bud will cause all temporary output files to be
112 deleted once the process completes. You can then execute <tt>buildme</tt> like any other
113 executable.
114
115 <h4>Compiling with Rebuild</h4>
116
117 This option is the only one of the three listed here that works in a Tango environment,
118 but it also works in a Phobos environment. The command line is very similar to that
119 for Bud above:
120
121 <pre>
122     rebuild -clean buildme.d
123 </pre>
124
125 The <tt>-clean</tt> option will cause most of the temporary output files to be deleted.
126 But Rebuild currently does not delete MAP files generated by DMD on Windows, so you will
127 have a buildme.map lying around in the directory after execution.
128
129 <h4>Options</h4>
130 Whether you run <tt>buildme.d</tt> as a script or compile it into an executable,
131 you first need to decide which libraries you want to build and how you want to build them.
132 There are a few command line options you can pass along. With the exception of the
133 'cleanlib' option, all options may be passed in any order.
134 <p>
135 By default, each package will be built in Release mode. You can specify debug
136 mode by passing 'debug' on the command line:
137
138 <pre>
139     dmd -run buildme.d debug
140 </pre>
141
142 Or, for the compiled form:
143
144 <pre>
145     buildme debug
146 </pre>
147
148 The script also accepts 'release' as a command line argument.
149 </p><p>
150 The build script generates a temporary build response file that is deleted at the
151 end of execution. Sometimes, when debugging problems with the build script, it
152 is necessary to see the contents of this file. You can prevent the script from
153 deleting the file by passing 'nodelbrf' on the command line:
154
155 <pre>
156     dmd -run buildme.d nodelbrf
157 </pre>
158
159 Or for the compiled form:
160
161 <pre>
162     buildme nodelbrf
163 </pre>
164
165 You can also pass options to both Bud and the compiler, though not via the command
166 line. This is done through the following three options files:
167
168 <pre>
169 $(DERELICT_HOME)/buildopts/bud_common.txt
170 $(DERELICT_HOME)/buildopts/bud_release.txt
171 $(DERELICT_HOME)/buildopts/bud_debug.txt
172 </pre>
173
174 Options in <tt>bud_common.txt</tt> are used in both Debug and Release builds. The other
175 two are self-explanatory.
176 </p><p>
177 The rules for editing these files are the same as those for editing
178 <a href="http://build.dsource.org/response_file.html">Bud Response Files</a>,
179 but there are some caveats. Because <tt>buildme.d</tt> automates the build process,
180 some assumptions are made. The first is that the output directory will be the
181 <tt>$DERELICT_HOME/lib</tt> subdirectory. Adding -TsomeDir to any of the three
182 files will have no effect. Second, the import paths for building each package
183 are set automatically so that you don't need to. Third, the DerelictUtil package
184 and other dependencies are excluded from the compilation automatically via the
185 -X Bud option (except, of course, when DerelictUtil itself is being compiled).
186 </p><p>
187 For most users, the default configuration should suffice.
188 </p>
189
190 <h4>Which Packages?</h4>
191 If you only want to build one or more specific packages, rather than all of them,
192 you can specify the package names on the command line:
193
194 <pre>
195     cd $DERELICT_HOME
196     dmd -run buildme.d DerelictAL DerelictUtil
197 </pre>
198
199 Or for the compiled form:
200
201 <pre>
202     cd $DERELICT_HOME
203     buildme DerelictAL DerelictUtil
204 </pre>
205
206 The above will build only the DerelictAL and DerelictUtil libraries.
207
208 <h4>Cleaning Up</h4>
209 During compilation, all object files will be deleted by the script. If you want
210 to delete all of the libraries, you can do so with the following command:
211
212 <pre>
213     cd $DERELICT_HOME
214     dmd -run buildme.d cleanlib
215 </pre>
216
217 Or for the compiled form:
218
219 <pre>
220     cd $DERELICT_HOME
221     buildme cleanlib
222 </pre>
223
224 This will delete the libraries in $(DERELICT_HOME/lib). Unlike the other command
225 line options, this option is exclusive to other options. If any options precede it,
226 it will be ignored. Likewise, any options following it will be ignored.
227
228 <h4>Troubleshooting</h4>
229 If you have any problems building Derelict with Bud, you may direct them to the
230 <a href="http://www.dsource.org/forums/viewforum.php?f=19&sid=d6f86cfb804d7c8727af1f58cd327d2c">Derelict Forums</a>
231 and someone will try to help you. Please don't post problems on the Bud forums
232 unless you are absolutely certain the problem is with Bud and not with Derelict.
233
234 </body>
235 </html>
Note: See TracBrowser for help on using the browser.