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 create a simple
  22 text file containing a list of the required compilation units.
  23 on the next invocation, it will compile the target by simply passing all required C files to
  24 the compiler in one turn. this is much faster than compiling every C file on its own, and
  25 allows to use the same CFLAGS on all of them, and do nice optimization stuff like -flto and
  26 -fwhole-program, which only work really nicely if the compiler gets all C files in exactly
  27 one statement.
  28
  29 RcB tags
  30 --------
  31 //RcB: CMD "param"
  32
  33 "//RcB:" tells rcb that a rcb command starts here, and is treated by the
  34 C compiler as a comment.
  35
  36 currently implemented commands:
  37 DEP    tells rcb to add param to the dependency tree.
  38 LINK   tells rcb to pass param to the compiler (i.e. "-lSDL").
  39        it is advisable to use this only in your main .c file.
  40
  41
  42 CFLAGS and co
  43 -------------
  44 RcB uses the following environment variables:
  45 CFLAGS
  46 CC
  47 NM
  48
  49 linking to libraries
  50 --------------------
  51 if you need to link to a specific library, you can pass it to rcb after the
  52 name of the main C file.
  53 just run rcb without arguments to see a list of options.
  54
  55
  56 gotcha's
  57 --------
  58 * by default, rcb uses existing .o files to speed up the process.
  59   however this can lead to some newly added symbols not being found.
  60   in this case use --force to force rcb to recompile everything.
  61
  62 * after renaming or moving stuff around, the information in the .rcb file gets
  63   invalid. use --new to force rcb to remove the rcb file and recollect dependency
  64   information.
  65
  66 * after changing some defines, it is advisably to run rcb twice with --force.
  67   this will make sure that the C files will be thrown at the compiler instead
  68   of the object files which may contain/lack (un)wanted code from previous
  69   compilations.
  70
  71 so the rule of thumb is, whenever you run into problems
  72 - check that an rcb tag for your .c file exists
  73 - run rcb with --new and --force, followed by a second run with --force only.