Documentation/automake.txt

   1
   2 automake.inc provides a simple mechanism for downloading/patching/building
   3 and installing packages within the uClinux-dist framework.
   4
   5 How to use it is documented below by example.
   6
   7 Using this build system requires a working net connection (at least for the
   8 first time you turn on a package in the build).  All downloaded files will
   9 be stored in ~/.downloads. If you want to share downloads to save bandwidth
  10 or time you can copy this directory or mount it as a shared filesystem.  It
  11 is just a directory of files.
  12
  13 For this example we will work through the steps needed to add a package
  14 called "mypkg":
  15
  16 1) Create user/mypkg
  17
  18 2) Add user/mypkg/Makefile
  19
  20       URL = http://mypkg.net/downloads/mypkg-1.2.tar.gz
  21       include $(ROOTDIR)/tools/automake.inc
  22
  23    or if you want to build more than one package:
  24
  25       mkpkg-1.2_URL   = http://mypkg.net/downloads/mypkg-1.2.tar.gz
  26       yourpkg-2.3_URL = http://yourpkg.net/downloads/yourpkg-2.3.tar.gz
  27
  28       AUTOMAKE_y = mypkg-1.2 yourpkg-2.3
  29
  30       include $(ROOTDIR)/tools/automake.inc
  31
  32 3) Put your patches in user/mypkg/patches/.
  33
  34    Patches can be of the form:
  35
  36       mypkg-1.2-fix-strcpy.patch
  37       mypkg-1.2-more-fixes.patch
  38
  39    or in quilt format with a "series" files listing the patches in the order
  40    the need to be applied.
  41
  42    Patches should apply with -p1 from the top directory in the extracted
  43    tarball.
  44
  45 4) Run "make oldconfig" which will let you enable your new application in
  46    the build.
  47
  48 5) try building ;-),  if you have already built a full tree you can just
  49    run:
  50
  51       make user/mypkg_only
  52
  53    or run "make" from the top level.
  54
  55 6) Customising your new package.
  56
  57    Extra variables you can add to your makefile to customise how the package
  58    is built,  followed by an example.
  59
  60    PKG = name     - override PKG name,  normally drived from URL
  61
  62       PKG = mypkg
  63
  64    <pkg>_CONFOPTS - configure options needed to build package
  65
  66       mypkg-1.2_CONFOPTS = --with-installed-zlib
  67
  68    <pkg>_CONFVARS - env vars passed to configure to override settings
  69
  70       mypkg-1.2_CONFVARS = ac_cv_func_posix_getpwuid_r=yes
  71
  72    <pkg>_CFLAGS   - CFLAGS needed to build package
  73
  74       mypkg-1.2_CFLAGS = -DPTYS_ARE_GETPT=1
  75
  76    <pkg>_BUILDDIR - if the subdir to build in isn't <pkg> after extraction,
  77                     patches apply -p1 within this directory.
  78
  79       mypkg-1.2_BUILDDIR = mypkg/src
  80
  81    <pkg>_MAKEVARS - variables to force when making
  82
  83       mypkg-1.2_MAKEVARS = LIBS=-lintl
  84
  85    <pkg>_ROMFS    - package specific romfs make target to be run after default
  86                     romfs target
  87
  88    <pkg>_METHOD   - The default method is to treat URL as a tarball/zip
  89                     download.  You may set method to "git" or "gitarchive".
  90                     "git" will clone the remote repo and build with that.
  91                     "gitarchive" will run the git archive command to obtain
  92                     a tarball of just a given "SUBDIR".  URL is used to
  93                     specify the remote repository.  VERSION may be used to
  94                     specifiy a version or branch.
  95
  96    <pkg>_VERSION  - for revision controlled packages,  you can set the
  97                     version.
  98
  99    <pkg>_SUBDIR   - when using the gitarchive method to obtain
 100                     subdirectories of larger projects,  this is the
 101                     subdirectory under the projects git root.
 102
 103    <pkg>_DOWNLOADNAME
 104                   - Sometimes the URL does not provide a nicely named file,
 105                     this option allows the locally used archive name to be
 106                     set.
 107
 108    <pkg>_MAKEVARS - vars to add to all make commands, ie., make CC=gcc.
 109
 110    <pkg>_BUILDVARS
 111    <pkg>_INSTALLVARS
 112                   - environment or vars that are set before building(make)
 113                     or installing.
 114
 115    In many cases the individual <pkg> options can be set globally to apply
 116    to one or more packages.  For example the follow sets CONFOPTS for all
 117    packages built by this automake file:
 118
 119       CONFOPTS = my-conf-options
 120
 121    Other such shortcust are:
 122
 123       URL, METHOD, BUILDDIR, SRCDIR, DOWNLOADNAME, CONFIGURE, SUBDIR,
 124       VERSION, AUTOCONF, NODEFCONF, INSTALL, METHOD
 125
 126    Some othe global only overrides are:
 127
 128       AUTOMAKE_ROMFS - override the main romfs target,  you have complete
 129                        control.
 130       BUILDTARGET    - (defaults to built)
 131       INSTALLTARGET  - defaults to installed
 132       FINALTARGET    - defaults to lndir
 133       COMPLETETARGET - default to complete_target
 134
 135    The above overrides can be used to gain control over the build at various
 136    points.
 137
 138    You can also add your own Kconfig file if you want fine grained config
 139    control.  If you do not provide a Kconfig a simple version will be
 140    created for you automatically at config time.  If you do add your own
 141    Kconfig file then you must include a top level config option to build
 142    your new directory, for example, a Kconfig for a packge with one extra
 143    option:
 144
 145       config USER_MYPKG
 146       bool "mypkg"
 147       help
 148          This is mypkg
 149
 150       config USER_MYPKG_OPTION
 151       bool "mypkg: simple option"
 152       depends on USER_MYPKG
 153       default n
 154       help
 155          Change the mypkg build in some useful way.
 156
 157    If you add your library/application to the "lib" directory,  then change
 158    all occurances of of the text USER in the above example to LIB.
 159
 160 Copyright (C) 2009 David McCullough <davidm@uclinux.org>