README

   1 INTRODUCTION
   2 ============
   3
   4 The "dotmk" project is composed by a set of GNU make scripts that are able to
   5 simplify drastically the Makefile creation process. If your project needs to
   6 use GNU make to compile its software, "dotmk" can simplify all the complicated
   7 process of rules definitions and compiler commands creation. This task
   8 sometimes takes lots of time to understand, define and debug, but "dotmk" does
   9 it just by setting a couple of variables and a "include" line.
  10
  11 For now "dotmk" is only able to handle two basic tasks: C/C++ software building
  12 (compilation and linking) and recursive calling GNU make in subdirectories. We
  13 intent to implement other objectives like Doxygen extraction, LaTeX documents
  14 compilation or Java support but this will come over the time. The instructions
  15 to install "dotmk" in your project and execute each task follows.
  16
  17
  18 INSTALL
  19 =======
  20
  21 The installation process consists in the building of GNU make scripts under a
  22 directory called "mk" in the project which will use "dotmk". The result will be
  23 just that the project will contain that "mk" directory with some ".mk" files in
  24 it.
  25
  26 To do that, unpack the "dotmk" package and call its "install.sh" script with a
  27 target directory as its argument:
  28
  29   $ tar -xzf dotmk-0.2.tar.gz
  30   $ cd dotmk
  31   $ ./install.sh ~/my-project
  32
  33 And that will create the "~/my-project/mk" directory with a few ".mk" files in
  34 it. That will enable the use of "dotmk" in that project and you can proceed
  35 with the Makefile creation in the next section.
  36
  37
  38 TASKS
  39 =====
  40
  41 Building C/C++ Software
  42 -----------------------
  43
  44 The building process of a software coded in the C/C++ language is usually
  45 simple. It consists in compiling its source code and linking the resulted
  46 objects into one binary module, which might be a library or a executable. There
  47 may be more details in this process, but this is the simplest example.
  48
  49 To build a Makefile without the "dotmk" project you would need to know how to
  50 define its rules (which are not that simple), call GCC with its compiling
  51 arguments, linking options and maybe AR. With "dotmk" you need to include the
  52 following 3 intuitive lines in the Makefile file:
  53
  54   PROG=foobar
  55   SRCS=foo.c bar.c
  56   include mk/build.mk
  57
  58 This would instruct GNU make compile the "foo.c" and "bar.c" files and link
  59 them into the "foobar" executable. The last line just tells make to include
  60 "dotmk" scripts. After that you just need to execute the following line to
  61 build it.
  62
  63   $ make
  64
  65 Very simple, uh?
  66
  67 One of the great things of "dotmk" is that it doesn't only define the building
  68 targets, but the dependency detection and cleaning ones also. To create the
  69 ".depend" file (please look at "mkdep" manual to understand what it is) you
  70 need to call:
  71
  72   $ make dep
  73
  74 And to finally clean all that mess you can call:
  75
  76   $ make clean
  77
  78 It would clean all the built objects (create with the default "make" command),
  79 but not the ".depend" file. To clean all the remaining file you would need to
  80 call:
  81
  82   $ make distclean
  83
  84 And that's it.
  85
  86 If you need to build a library just change the "PROG" variable name to "LIB":
  87
  88   LIB=foobar
  89   SRCS=foo.c bar.c
  90   include mk/build.mk
  91
  92 This would build the "libfoobar.so" and "libfoobar.a" binaries, but without
  93 version definition. We intent to implement soon that too.
  94
  95 If you need to build more than one executable or library, use "PROGS" or "LIBS"
  96 and prefix every "SRCS" line with the name of the program (or library) followed
  97 by a underline. For example:
  98
  99   PROGS=foobar qwerty
 100   foobar_SRCS=foo.c bar.c
 101   qwerty_SRCS=qwe.c rty.c
 102   include mk/build.mk
 103
 104 If you need to build the "foobar" and "qwerty" programs AND the "asdfgh" and
 105 "zxcvbn" libraries:
 106
 107   PROGS=foobar qwerty
 108   LIBS=asdfgh zxcvbn
 109   foobar_SRCS=foo.c bar.c
 110   qwerty_SRCS=qwe.c rty.c
 111   asdfgh_SRCS=asd.c fgh.c
 112   zxcvbn_SRCS=zxc.c vbn.c
 113   include mk/build.mk
 114
 115 And if you need to include library dependency, dynamic (.so) or static (.a),
 116 use the "LIBDIRS" and "DEPLIBS" variables:
 117
 118   PROGS=foobar
 119   foobar_SRCS=foo.c bar.c
 120   # libfftw.so is under /usr/local/lib
 121   foobar_LIBDIRS=/usr/local/lib
 122   foobar_DEPLIBS=fftw /opt/gtest/lib/libgtest.a ../lame.a
 123   include mk/build.mk
 124
 125 To include already compiled objects in your binary use the OBJS variable:
 126
 127   PROG=foobar
 128   SRCS=main.c
 129   OBJS=../closed/source.o
 130   include mk/build.mk
 131
 132 For headers dependency (include) there is the "INCDIRS" variable:
 133
 134   PROG=foo
 135   SRCS=main.c
 136   INCDIRS=/opt/bar/include
 137   include mk/build.mk
 138
 139 You could think that this is beginning to be too complicated but, believe me,
 140 with only GNU make the Makefile would be *MUCH* more complicated.
 141
 142
 143 Recursive Calling in Subdirectories
 144 -----------------------------------
 145
 146 If you have a project with lots of programs or libraries to be compiled, maybe
 147 a good way to organize them would be dividing it into subdirectories. For
 148 example, if you have the "foo" program and the "bar" library, you could create
 149 a project tree as:
 150
 151   .
 152   |-- Makefile
 153   |-- bar
 154   |   |-- Makefile
 155   |   `-- main.c
 156   |-- foo
 157   |   |-- Makefile
 158   |   `-- main.c
 159   `-- mk
 160       |-- build.mk
 161       `-- subdir.mk
 162
 163 To simplify the "make" command calls without the need to enter it two or more
 164 times, you could use "dotmk" by just creating the following Makefile the main
 165 directory:
 166
 167   SUBDIRS=bar foo
 168   include mk/subdir.mk
 169
 170 This would enable the recursive call for the "all", "clean", "distclean" and
 171 "install" targets.
 172
 173
 174 Global definitions
 175 ------------------
 176
 177 There are situations where you need to set a variable for every Makefile that
 178 is called. For these times you need to create a local "mk" file. The name of
 179 the file must be the base name of the "mk" file you want to precede, suffixed
 180 by the "-local.mk" name and created in the same directory where that "mk" file
 181 is.
 182
 183 For example, if you need to set the PREFIX variable to install all files of
 184 your project in a different directory, do it in the "build-local.mk" file under
 185 the same directory where the original "build.mk" file is:
 186
 187   $ echo PREFIX=/opt/foobar >> mk/build-local.mk
 188
 189 And then every "make install" command called will install the built files under
 190 the "/opt/foobar" directory.
 191
 192
 193 Cross Compiling
 194 ---------------
 195
 196 The cross compiling procedure is pretty simple: just set the CROSS_COMPILE
 197 variable. Example:
 198
 199   CROSS_COMPILE=arm-linux-gnu-
 200   PROG=foo
 201   SRCS=main.cpp foo.c bar.c FooBar.cpp
 202   include ../mk/build.mk
 203
 204 This would compile the "eptime" for ARM processor using arm-linux-gnu-gcc and
 205 arm-linux-gnu-g++ as the compilers and arm-linux-gnu-g++ as the linker.
 206
 207 If you have a whole project which needs to be cross compiled, you can define
 208 that variable in the local "mk" file called "build-local.mk". For that just go
 209 to the directory where "dotmk" was installed and run:
 210
 211   $ echo CROSS_COMPILE=arm-linux-gnu- >> mk/build-local.mk