implement --hdrsrc substitution mechanism
[rofl0r-rcb.git] / README
blob1af598c6475f5f2424433a3a1c8f8ddce63aca71
1 RcB - rofl0r's C builder.
2 =========================
4 builds a C file holding a main method, by checking the headers it includes for
5 RcB tags.
6 such a tag might look like
8 //RcB: DEP "mylib/*.c"
9 //RcB: LINK "-lSDL"
11 the first one tells RcB that the symbols defined in this header can be found
12 in the listed C files.
13 after gathering all dependencies, it starts trying to compile the main file, 
14 and analyses the compiler output for which dependencies are not fulfilled. 
16 it then starts multiple passes in which it compiles each referenced C file 
17 into an object file, and scans the symbols it defines. 
18 if those match the missing ones, the file will be added to the list of final
19 dependencies.
21 finally if there are no missing deps left, it will link them all together and
22 create a simple text file containing a list of the required compilation units.
23 on the next invocation, it will compile the target by simply passing all
24 required C files to the compiler in one turn.
25 this is much faster than compiling every C file on its own, and allows to use
26 the same CFLAGS on all of them, and do nice optimization stuff like 
27 -flto -fwhole-program, which only work really nicely if the compiler gets all
28 C files in exactly one statement.
30 RcB tags
31 --------
32 //RcB: CMD "param"
34 "//RcB:" tells rcb that a rcb command starts here, and is treated by the
35 C compiler as a comment.
37 currently implemented commands:
38 DEP     tells rcb to add param to the dependency tree.
39 LINK    tells rcb to pass param to the compiler (i.e. "-lSDL").
40         it is advisable to use this only in your main .c file.
41 SKIPON  skip #include directives until SKIPOFF if param can be found inside
42         CFLAGS.
43         this is necessary to exclude headers that are conditionally used,
44         and pull in more deps.
45         necessary to workaround the fact that rcb doesn't have any means of
46         preprocessing C code.
47 SKIPOFF turn off skipping of #include directives if param can be found inside
48         CFLAGS.
49 SKIPUON same as SKIPON, but applies to all CFLAGS that are *NOT* found
50         on the command line.
51 SKIPUOFF same as SKIPOFF, but applies to all CFLAGS that are *NOT* found
52         on the command line.
53       
55 CFLAGS and co
56 -------------
57 RcB uses the following environment variables:
58 RCBFLAGS (can contain one or more rcb command line arguments)
59 CFLAGS
63 linking to libraries
64 --------------------
65 if you need to link to a specific library, you can pass it to rcb after the 
66 name of the main C file. 
67 just run rcb without arguments to see a list of options.
69 parallel builds
70 ---------------
71 on my wishlist, but currently not possible.
72 i usually build stuff with ~50 C files, which takes about 10-15 secs.
74 gotcha's
75 --------
76 * by default, rcb uses existing .o files to speed up the process.
77   however this can lead to some newly added symbols not being found.
78   in this case use --force to force rcb to recompile everything.
80 * after renaming or moving stuff around, the information in the .rcb file gets
81   invalid. use --new to force rcb to remove the rcb file and recollect
82   dependency information.
83   NOTE:
84   it is much safer to use --new than starting to delete .rcb files manually.
85   if you're in a rush you might erase your c file instead of the rcb file
86   accidentally.
88 * after changing some defines, it is advisably to run rcb twice with --force.
89   the first run will recompile all c files to object files (so that the symbols
90   can be checked) and link them together,
91   the second one will then use all the necessary C files for a clean recompile.
92   this will make sure that the C files will be thrown at the compiler instead
93   of the object files which may contain/lack (un)wanted code from previous
94   compilations.
96 so the rule of thumb is, whenever you run into problems
97 - check that an rcb tag for your .c file exists
98 - run rcb with --new and --force, followed by a second run with --force only.
99 - if the problem persists, add --verbose and inspect which dependendiecs get
100   pulled in from where.