doc/PORTING

   1
   2 1. unpack the source tarball and cd to the resulting dir
   3
   4 2. # autoconf
   5    this reads configure.in and generates the ./configure script
   6
   7 3. # ./configure
   8    this probes your system and then, for each "file" named
   9    in the AC_OUTPUT() macro near the end of configure.in,
  10    read "file".in and generate "file". Variables named @somevariable@
  11    will be substituted with literal values.
  12
  13 4. step (3) produces several files. These files are generated by
  14    configure from their respective .in file in the same directory.
  15    You should have a read of these generated files and diff them
  16    against their respective .in files to see what was substituted
  17    by configure.
  18
  19    src/include/builddefs
  20         common definitions for the build environment. This is included
  21         by all Makefiles, in conjunction with src/include/buildrules.
  22         Note that most autoconf/configure build environments generate
  23         Makefile (from Makefile.in) in every src dir. Instead, we
  24         generate builddefs, and then include it in every Makefile.
  25
  26    src/include/platform_defs.h
  27         header containing conditional macros defining the C run-time
  28         environment discovered by the configure script.
  29
  30 5. read some or all of the GNU tool chain documentation
  31    GNU make :
  32        http://www.delorie.com/gnu/docs/make/make_toc.html
  33    autoconf :
  34         http://www.delorie.com/gnu/docs/autoconf/autoconf_toc.html
  35    libtool :
  36         http://www.delorie.com/gnu/docs/libtool/libtool_toc.html
  37    gcc/g++ :
  38         http://www.delorie.com/gnu/docs/gcc/gcc_toc.html
  39
  40 6. Makefiles and build environment
  41    First have a look at some Makefiles
  42
  43         example using SUBDIRS :  attr/Makefile
  44         example static library:  attr/libattr/Makefile
  45         example command       :  attr/getfattr/Makefile
  46
  47    All Makefiles must define TOPDIR as the root of the project. This
  48    allows other stuff to be found relative to $(TOPDIR).
  49
  50    All Makefiles should have the following structure, which is
  51    much like commondefs and commonrules in the IRIX build environment, e.g.
  52
  53    # ----------------------------------------------------------------------
  54    # TOPDIR must point to the root of the project
  55    # The builddefs file defines lots of things. Read it.
  56    TOPDIR = ..
  57    include $(TOPDIR)/include/builddefs
  58
  59    # first rule should always be "default"
  60    default : sometarget
  61         commands to build targets, if necessary
  62
  63    # $(BUILDRULES) is defined in builddefs and includes rules for
  64    # descending subdirs, building targets and installation rules
  65    include $(BUILDRULES)
  66
  67    install : default
  68         $(INSTALL) sometargets somewhere
  69    # ----------------------------------------------------------------------
  70
  71 7. packaging
  72
  73    # ./Makepkgs
  74    this script generates all of the packages supported - each has a
  75    subdirectory below attr/build where knowledge specific to each
  76    package type is maintained.
  77
  78    The script produces logs of each stage of the build (this info is
  79    also echoed to the screen when the "verbose" option is provided):
  80
  81         attr/Logs/configure     - `autoconf; ./configure' output
  82         attr/Logs/default       - `make default' output
  83         attr/Logs/dist          - `make build dist' output
  84
  85    On successful completion, the script echoes the names of packages
  86    successfully generated.