root/trunk/rebuild/README

Revision 522, 2.8 kB (checked in by Gregor, 7 years ago)

Thu Apr 19 15:18:40 PDT 2007 Richards@codu.org

  • Adde pre/post digen commands.

Thu Apr 19 14:17:05 PDT 2007 Richards@codu.org

  • rebuild/mars.c: Added flags= variable to configuration files.

Thu Apr 19 14:07:36 PDT 2007 Richards@codu.org

  • MERGE: DMD 1.013

Thu Apr 19 14:07:10 PDT 2007 Richards@codu.org

  • Local branch.
Line 
1 Rebuild is a tool for building D software. It is based on the frontend to the
2 DMD D compiler.
3
4 Essentially, for any D source file given, rebuild finds all dependencies, and
5 compiles them all into the target. Compiling a D program with rebuild is, for
6 example:
7
8 rebuild foo/foo.d -offood
9
10 In this example, a program called fooD is compiled with the main source file
11 being foo/foo.d.
12
13
14 Rebuild can also compile libraries. The -lib flag to rebuild causes it to
15 generate a library instead of a binary:
16
17 Windows+DMD: rebuild -lib foo/foo.d -offoo.lib
18 Otherwise:   rebuild -lib foo/foo.d -oflibfoo.a
19
20
21 A useful flag when generating libraries is -explicit, which will cause it /not/
22 to include all the dependencies. For example, if foo/foo.d imports foo/bar.d,
23 then:
24 rebuild -lib foo/foo.d -oflibfoo.a
25 will include foo/bar.d in the target library, but
26 rebuild -lib -explicit foo/foo.d -oflibfoo.a
27 will not.
28
29
30 On some platforms (presently, GDC on Posix), it is also possible to build
31 shared libraries. From rebuild's perspective, a shared library must be able to
32 be used interchangeably with a standard library, so DMD's .dll's on Windows are
33 not supported. Such shared libraries can be built with:
34
35 rebuild -shlib -explicit foo/foo.d -oflibfoo.so
36
37
38 Rebuild allows you to save options usually passed to rebuild in a response
39 file. Use one line per argument, then choose the response file with:
40
41 rebuild -rf<filename>
42
43
44 Rebuild also accepts a few special pragma()'s in source files. These must be in
45 a version(build) block. The two supported pragmas are link and export_version.
46
47 pragma(link) is useful for indicating that a D source file depends on a
48 specified library. If the file depended on libxml2, for example, pragma(link)
49 would be used like so:
50
51 version(build) {
52     pragma(link, "xml2");
53 }
54
55 On Posix and MingW, this links with -lxml2 (so it will link to libxml2.a or
56 libxml2.so). On Windows, this links to xml2.lib.
57
58
59 pragma(export_version) is used to set a version identifier for all source files
60 (as opposed to version=, which sets it only for a single source file):
61
62 version (build) {
63     pragma(export_version, "setversion");
64 }
65
66
67 Rebuild has a large number of other available options. This document does not
68 list all of them. Use
69 rebuild --help
70 to get the entire list.
71
72
73 Rebuild uses configuration files for almost everything it does. These
74 configuration files are in the directory rebuild.conf, which is installed
75 either as /etc/rebuild or simply as rebuild.conf next to rebuild[.exe]. For the
76 most part, you should not need to edit them, but there are some options you may
77 wish to add:
78
79 include=<path>          Adds <path> to the include path rebuild uses.
80 path=<path>             Adds <path> to $PATH (or %PATH%) during each rebuild
81                         run.
82 flags=<flags>           Acts as though <flags> were passed with every rebuild
83                         run.
Note: See TracBrowser for help on using the browser.