README

   1 RcB - rofl0r's C builder.
   2 =========================
   3
   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
   7
   8 //RcB: DEP "mylib/*.c"
   9 //RcB: LINK "-lSDL"
  10
  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.
  15
  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.
  20
  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.
  29
  30 RcB tags
  31 --------
  32 //RcB: CMD "param"
  33
  34 "//RcB:" tells rcb that a rcb command starts here, and is treated by the
  35 C compiler as a comment.
  36
  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
  50
  51 CFLAGS and co
  52 -------------
  53 RcB uses the following environment variables:
  54 RCBFLAGS (can contain one or more rcb command line arguments)
  55 CFLAGS
  56 CC
  57 NM
  58
  59 linking to libraries
  60 --------------------
  61 if you need to link to a specific library, you can pass it to rcb after the
  62 name of the main C file.
  63 just run rcb without arguments to see a list of options.
  64
  65 parallel builds
  66 ---------------
  67 on my wishlist, but currently not possible.
  68 i usually build stuff with ~50 C files, which takes about 10-15 secs.
  69
  70 gotcha's
  71 --------
  72 * by default, rcb uses existing .o files to speed up the process.
  73   however this can lead to some newly added symbols not being found.
  74   in this case use --force to force rcb to recompile everything.
  75
  76 * after renaming or moving stuff around, the information in the .rcb file gets
  77   invalid. use --new to force rcb to remove the rcb file and recollect
  78   dependency information.
  79   NOTE:
  80   it is much safer to use --new than starting to delete .rcb files manually.
  81   if you're in a rush you might erase your c file instead of the rcb file
  82   accidentally.
  83
  84 * after changing some defines, it is advisably to run rcb twice with --force.
  85   the first run will recompile all c files to object files (so that the symbols
  86   can be checked) and link them together,
  87   the second one will then use all the necessary C files for a clean recompile.
  88   this will make sure that the C files will be thrown at the compiler instead
  89   of the object files which may contain/lack (un)wanted code from previous
  90   compilations.
  91
  92 so the rule of thumb is, whenever you run into problems
  93 - check that an rcb tag for your .c file exists
  94 - run rcb with --new and --force, followed by a second run with --force only.
  95 - if the problem persists, add --verbose and inspect which dependendiecs get
  96   pulled in from where.