doc/make+-book.xml

   1 <book>
   2   <bookinfo>
   3     <title><application>make+</application> users manual</title>
   4     <authorgroup>
   5       <author>
   6         <firstname>Richard</firstname>
   7         <othername>W.M.</othername>
   8         <surname>Jones</surname>
   9       </author>
  10     </authorgroup>
  11
  12     <date>21st December 2002</date>
  13     <releaseinfo>1.0</releaseinfo>
  14
  15     <abstract>
  16       <para>
  17         <application>make+</application> is an advanced build system
  18         designed to replace the functionality of
  19         <application>autoconf</application>,
  20         <application>automake</application>, and packaging systems
  21         such as <application>rpm</application>. Using a single control
  22         file, maintainers and end users can build and install the
  23         program, build RPMs, Debian packagages and other package
  24         formats, and maintain a website.
  25         <application>make+</application> is just a set of GNU
  26         <application>make</application> snippets and shell scripts,
  27         making it simple to maintain and extend.
  28       </para>
  29     </abstract>
  30
  31     <keywordset>
  32       <keyword>make+</keyword>
  33       <keyword>make</keyword>
  34       <keyword>automake</keyword>
  35       <keyword>autoconf</keyword>
  36       <keyword>rpm</keyword>
  37       <keyword>deb</keyword>
  38       <keyword>dpkg</keyword>
  39       <keyword>package</keyword>
  40     </keywordset>
  41   </bookinfo>
  42
  43   <chapter>
  44     <title>Introduction</title>
  45
  46     <para>
  47       <application>make+</application> is an advanced build system
  48       designed to replace the functionality of
  49       <application>autoconf</application>,
  50       <application>automake</application>, and packaging systems such
  51       as <application>rpm</application>. Using a single control file,
  52       maintainers and end users can build and install the program,
  53       build RPMs, Debian packagages and other package formats, and
  54       maintain a website.
  55     </para>
  56
  57     <para>
  58       At the same time, <application>make+</application> is just a set
  59       of GNU <application>make</application> snippets and shell
  60       scripts, making it simple to maintain and extend.
  61     </para>
  62
  63     <para>
  64       This manual explains how to convert your own package to use
  65       <application>make+</application>. If you have been presented
  66       with a package which contains a <filename>Makefile+</filename>
  67       file and you want to know how to use <command>make+</command> to
  68       build and install this package, then please read the
  69       <command>make+(1)</command> manual page.
  70     </para>
  71
  72   </chapter>
  73
  74   <chapter id="theory-of-operation">
  75     <title><application>make+</application> theory of operation</title>
  76
  77     <para>
  78       A <application>make+</application>-enabled package
  79       contains a single file called <filename>Makefile+</filename>
  80       located in the top-level source directory.
  81       <application>make+</application> should never
  82       be used recursively, so you will not need more than
  83       one <filename>Makefile+</filename> file even if your
  84       package source contains subdirectories.
  85     </para>
  86
  87     <para>
  88       <application>make+</application> has the notion of a "pristine"
  89       source directory. This means that
  90       <application>make+</application> should never create
  91       intermediate files (object files, Java class files and the like)
  92       directly in the source directory. Instead,
  93       <application>make+</application> creates a build directory
  94       before it starts to store intermediate build files. Normally
  95       this directory is called something like
  96       <filename>build-i686-unknown-linux</filename> but it may, of
  97       course, be something different on your particular machine and
  98       operating system.
  99     </para>
 100
 101     <para>
 102       The <command>make+</command> command is a shell script
 103       which performs the following steps:
 104     </para>
 105
 106     <itemizedlist>
 107       <listitem>
 108         <para> Creates the build directory if it doesn't exist already. </para>
 109       </listitem>
 110       <listitem>
 111         <para> Change into the build directory, ie.
 112           <command>cd build-foo-bar</command> </para>
 113       </listitem>
 114       <listitem>
 115         <para> Set the GNU <application>make</application> environment
 116           variable <envar>MAKEFILES</envar>. This causes GNU
 117           <application>make</application> to load the
 118           <application>make+</application> library first. </para>
 119       </listitem>
 120       <listitem>
 121         <para> Run <command>gmake -f ../Makefile+</command>. Because
 122           <envar>MAKEFILES</envar> has been set, GNU make will
 123           first load the <application>make+</application> library,
 124           and second load <filename>Makefile+</filename> from the
 125           top level of the source directory. </para>
 126       </listitem>
 127     </itemizedlist>
 128
 129     <para>
 130       Because <application>make+</application> runs in the
 131       build subdirectory, intermediate files shouldn't
 132       pollute the source directory. For this reason,
 133       <application>make+</application> can use a very
 134       simple scheme when it builds a source tarball of
 135       the package: it just treats every file in the source
 136       directory as a source file, ignoring only the
 137       build subdirectory itself and files with names
 138       like <filename>foo~</filename> and <filename>CVS</filename>.
 139     </para>
 140
 141   </chapter>
 142
 143   <chapter>
 144     <title>Compiling a package which has been converted to use
 145       <application>make+</application></title>
 146
 147     <para>
 148       If you have been given an application which has been
 149       converted to use <application>make+</application> already
 150       and you just want to compile it, then you're likely to
 151       read the generic <filename>INSTALL</filename> file and
 152       follow those instructions. This chapter explains the
 153       steps needed to compile an application, but also covers
 154       what's happening "behind the scenes" at each step.
 155     </para>
 156
 157     <para>
 158       The basic steps for compiling a <application>make+</application>-enabled
 159       application are:
 160     </para>
 161
 162     <itemizedlist>
 163       <listitem>
 164         <para> Configure the application using
 165           <command>./configure</command> </para>
 166       </listitem>
 167       <listitem>
 168         <para> Compile the application by typing
 169           <command>make+</command> </para>
 170       </listitem>
 171       <listitem>
 172         <para> Run any supplied tests by typing
 173           <command>make+ test</command> </para>
 174       </listitem>
 175       <listitem>
 176         <para> Install the application (as root) with
 177           <command>make+ install</command> </para>
 178       </listitem>
 179     </itemizedlist>
 180
 181     <para>
 182       But what is actually happening at each step?
 183     </para>
 184
 185     <sect1>
 186       <title>Configuration</title>
 187
 188       <para>
 189         The configuration step sets up the installation paths and then
 190         examines the system looking for required and optional programs
 191         and libraries.
 192       </para>
 193
 194       <para>
 195         We can imagine a fictional C debugging library. This requires
 196         the GNU <application>bfd</application> library to read
 197         executables. In addition, if the Linux-specific
 198         <function>backtrace</function> function is present in
 199         <application>libc</application>, then our fictional library
 200         can present more readable stack traces when a program
 201         crashes. The configure step for this library would first
 202         examine the system looking for the GNU
 203         <application>bfd</application> library. If not found, it would
 204         stop with an error, telling the user that they must install
 205         this library. It would then look for the
 206         <function>backtrace</function> function, but if this function
 207         was not present, it would not be a fatal error.
 208       </para>
 209
 210       <para>
 211         During the configuration step is also the point where we
 212         specify where we want to install the program. Normally
 213         users will be interested in setting the <envar>prefix</envar>
 214         variable which controls the overall location of the
 215         installation. It defaults to <filename>/usr/local</filename>
 216         which causes most files to be installed in subdirectories
 217         of this directory, but some users will want to change
 218         the prefix, commonly to <filename>/usr</filename>.
 219       </para>
 220
 221       <para>
 222         The result of the configuration step is three files in the
 223         build directory:
 224       </para>
 225
 226       <variablelist>
 227         <varlistentry>
 228           <term><filename>config.h</filename></term>
 229           <listitem>
 230             <para> A C/C++ header file describing the capabilities
 231               of the system. For our imaginary debugging library
 232               the C header file might look like this:
 233             </para>
 234
 235 <programlisting>
 236 /* Generated automatically by make+. */
 237
 238 #ifndef MP_CONFIG_H
 239 #define MP_CONFIG_H
 240
 241 #define PACKAGE "foo"
 242 #define VERSION "0.0.1"
 243 #define HAVE_LIBBFD 1
 244 #define HAVE_BACKTRACE 1
 245
 246 #endif /* MP_CONFIG_H */
 247 </programlisting>
 248
 249             <para>
 250               Happily we can see that this platform has both the
 251               required GNU bfd and the optional <function>backtrace</function>
 252               function.
 253             </para>
 254           </listitem>
 255         </varlistentry>
 256
 257         <varlistentry>
 258           <term><filename>config.mk</filename></term>
 259           <listitem>
 260             <para> This file is a <filename>Makefile</filename>
 261               fragment which is included directly the next time
 262               that <application>make+</application> runs (ie. it
 263               is included when we do the compile, test and
 264               install steps).
 265             </para>
 266
 267             <para>
 268               The purpose of this file is threefold. Firstly to
 269               define the <envar>LIBS</envar> variable, which
 270               is built on the fly as a result of detecting
 271               required and optional libraries. Secondly to
 272               save the installation paths (the <envar>prefix</envar>
 273               and related paths). Thirdly to save the results
 274               of the configuration tests in a way which is accessible
 275               to the <filename>Makefile+</filename>.
 276             </para>
 277
 278             <para>
 279               An extract from the <filename>config.mk</filename>
 280               file for our fictional debugging library:
 281             </para>
 282
 283 <programlisting>
 284 prefix     = /usr
 285 bindir     = /usr/bin
 286 sbindir    = /usr/sbin
 287 libexecdir = /usr/libexec
 288   #
 289   # many lines omitted
 290   #
 291 LIBS       = -lbfd
 292
 293 HAVE_LIBBFD = 1
 294 HAVE_BACKTRACE = 1
 295 </programlisting>
 296
 297           </listitem>
 298         </varlistentry>
 299
 300         <varlistentry>
 301           <term><filename>config.log</filename></term>
 302           <listitem>
 303             <para>
 304               This file logs every command issued during the
 305               configuration step, and is very useful for
 306               debugging problems.
 307             </para>
 308           </listitem>
 309         </varlistentry>
 310       </variablelist>
 311
 312       <para>
 313         <application>make+</application>-enabled applications come
 314         with a simple <command>configure</command> script. This is not
 315         just a convenience (users are used to typing
 316         <command>./configure --prefix=/usr</command>). It also removes
 317         the old <filename>config.mk</filename> file before running
 318         <command>make+ configure</command>, which is essential to
 319         ensure that any previous installation paths do not
 320         accidentally take precedence.
 321       </para>
 322
 323     </sect1>
 324
 325     <sect1>
 326       <title>Compiling and testing</title>
 327
 328       <para>
 329         The application's <filename>Makefile+</filename> file
 330         contains <filename>all</filename> and <filename>test</filename>
 331         targets, and, just like an ordinary
 332         <filename>Makefile</filename>, running
 333         <command>make+ all</command> or <command>make+ test</command>
 334         just executes these targets. However, recall from
 335         the <link linkend="theory-of-operation">theory of
 336           operation chapter</link>, before the application's
 337         <filename>Makefile+</filename> runs, the
 338         <application>make+</application> library is loaded
 339         first. Thus the application's <filename>all</filename> and
 340         <filename>test</filename> targets may - if they want -
 341         use macros and scripts from <application>make+</application>.
 342       </para>
 343
 344       <para>
 345         As an example, here is a typical <filename>test</filename>
 346         target, which makes use of the <application>make+</application>
 347         library's <envar>MP_RUN_TESTS</envar> macro:
 348       </para>
 349
 350 <programlisting>
 351 test: test_hash test_matvec test_pool
 352         $(MP_RUN_TESTS) $^
 353
 354 test_hash: test_hash.o
 355         $(CC) $(CFLAGS) $^ -o $@ $(LIBS)
 356 test_matvec: test_matvec.o
 357         $(CC) $(CFLAGS) $^ -o $@ $(LIBS)
 358 test_pool: test_pool.o
 359         $(CC) $(CFLAGS) $^ -o $@ $(LIBS)
 360 </programlisting>
 361
 362     </sect1>
 363
 364     <sect1>
 365       <title>Installing</title>
 366
 367       <para>
 368         The application's <filename>Makefile+</filename> file contains
 369         an ordinary <filename>install</filename> target which is run
 370         directly when the user does <command>make+ install</command>.
 371         The purpose of the <filename>install</filename> target is
 372         to do whatever is necessary to install the program, but
 373         in practice this means doing two things:
 374       </para>
 375
 376       <itemizedlist>
 377         <listitem>
 378         <para> Making the installation directories. </para>
 379         </listitem>
 380         <listitem>
 381           <para> Copying the program into the installation directories. </para>
 382         </listitem>
 383       </itemizedlist>
 384
 385       <para>
 386         Here is an example <filename>install</filename> target.
 387         The first four commands are concerned with creating the
 388         installation directories. The last five commands are concerned
 389         with copying the built program (in this case, a library) to
 390         the installation directories. Notice the use of several
 391         <application>make+</application> macros.
 392       </para>
 393
 394 <programlisting>
 395 install:
 396         install -d $(DESTDIR)$(libdir)
 397         install -d $(DESTDIR)$(pkgincludedir)
 398         install -d $(DESTDIR)$(man3dir)
 399         install -d $(DESTDIR)$(datadir)/rws/symtabs/
 400
 401         $(MP_INSTALL_STATIC_LIB) libc2lib.a
 402         $(MP_INSTALL_DYNAMIC_LIB) libc2lib.so
 403         install -m 0644 $(HEADERS) $(DESTDIR)$(pkgincludedir)
 404         install -m 0644 *.3        $(DESTDIR)$(man3dir)
 405         install -m 0644 *.syms     $(DESTDIR)$(datadir)/rws/symtabs/
 406 </programlisting>
 407
 408       <para>
 409         <filename>$(DESTDIR)</filename> must be prefixed onto every
 410         install path. Normally it is empty, and so has no
 411         effect. However when doing packaged builds (building RPMs for
 412         example) it can be used to create a "fake root".
 413       </para>
 414
 415       <para>
 416         <filename>$(libdir)</filename>, etc., are standard paths
 417         for particular directories. For example if the prefix
 418         is <filename>/usr/local</filename> and we are building
 419         on Linux, then
 420         <filename>$(libdir)</filename> will expand to
 421         <filename>/usr/local/lib</filename> and
 422         <filename>$(man3dir)</filename> to
 423         <filename>/usr/local/share/man/man3</filename>.
 424       </para>
 425
 426     </sect1>
 427
 428   </chapter>
 429
 430   <chapter>
 431     <title>Converting a package to use <application>make+</application></title>
 432
 433     <para>
 434       Converting a package to use <application>make+</application>
 435       is simple in principle. Step one is to create a file
 436       called <filename>Makefile+</filename> and place it in
 437       the top level directory of your package. Step two is
 438       to remove whatever existing build system you were
 439       using before - <filename>Makefile</filename>,
 440       <filename>configure.in</filename>, <filename>config.*</filename>,
 441       <filename>Makefile.am</filename> and so on. Of course
 442       step two is optional!
 443     </para>
 444
 445     <para>
 446       <application>make+</application> comes with a handy
 447       shell script called <command>make+-skeleton</command>
 448       which can help you to create your <filename>Makefile+</filename>
 449       file. You should run this in the top-level directory
 450       of your package. A typical interaction will go like this:
 451     </para>
 452
 453     <screen>
 454 <prompt>$</prompt> <command>make+-skeleton</command>
 455 <computeroutput>
 456 What is the name of your package? <userinput>foo</userinput>
 457
 458 Now I'm going to ask you for the initial version number for this
 459 package. Version numbers have two parts: the MAJOR part and the
 460 MINOR part.
 461
 462 The MAJOR part is a single number (eg 3). It is used (for example)
 463 for versioning libraries.
 464
 465 The MINOR part is two numbers separated by a single DOT (eg 1.0)
 466 This is the incremental release of the library.
 467
 468 If you library is version 3.1.0 then the MAJOR part would be
 469   3
 470 and the MINOR part would be
 471   1.0
 472
 473 What is the MAJOR part of the version? <userinput>0</userinput>
 474 What is the MINOR part of the version? <userinput>0.1</userinput>
 475
 476 I've written a Makefile+ file for you. You'll need to edit this file.
 477 Start by searching for all the 'XXX's and replacing them as necessary.
 478 </computeroutput>
 479     </screen>
 480
 481     <para>
 482       This creates the initial <filename>Makefile+</filename>
 483       for a package called <filename>foo</filename> at
 484       version 0.0.1. The <filename>Makefile+</filename> file
 485       will start like this:
 486     </para>
 487
 488     <example>
 489       <title><filename>Makefile+</filename> skeleton file</title>
 490 <programlisting>
 491 # -*- Makefile -*-
 492 #
 493 # This is a make+ file. Make+ is a set of scripts which enhance GNU
 494 # make and let you build RPMs, and other package types with just one
 495 # control file.  To build this package you will need to download make+
 496 # from this site: http://www.annexia.org/freeware/makeplus/
 497
 498 PACKAGE         := foo
 499 VERSION_MAJOR   := 0
 500 VERSION_MINOR   := 0.1
 501 VERSION         := $(VERSION_MAJOR).$(VERSION_MINOR)
 502
 503 SUMMARY         := XXX A ONE LINE SUMMARY OF YOUR PACKAGE
 504 COPYRIGHT       := XXX ONE LINE COPYRIGHT OR LICENSE
 505 AUTHOR          := XXX YOUR NAME AND EMAIL ADDRESS
 506 </programlisting>
 507     </example>
 508
 509     <para>
 510       Your first step should be to edit this file, search through for
 511       <literal>XXX</literal> and replace these as desired. (The
 512       following sections will help you to write each part of the
 513       file).
 514     </para>
 515
 516     <para>
 517       You should familiarise yourself with the
 518       <link linkend="theory-of-operation">theory
 519         of operation of <application>make+</application></link>
 520       too, particularly remembering that the
 521       <filename>Makefile+</filename> rules are run
 522       in the build subdirectory, not in the source
 523       directory.
 524     </para>
 525
 526     <sect1>
 527       <title>Configuration</title>
 528
 529
 530     </sect1>
 531
 532
 533
 534
 535
 536
 537
 538   </chapter>
 539
 540
 541 </book>