A-A-P home page | A-A-P Recipe Executive |
Prev | Tutorial | Next

## Chapter 11. A Ported Application

When an application already exists but for your system it requires a few tweaks, a port recipe can do the work. This can also be used for applications that work fine but you want to apply a number of patches or to add a feature. The recipe can be distributed, so that others can install the application without knowing the details. This works very much like the FreeBSD ports system.

This chapter is specifically for doing the port. If you are only interested in another kind of building you might want to skip this chapter.

## The Port Recipe

Since A-A-P is prepared for doing all the work, usually you only need to specify the relevant information, such as where to find the files involved. Here is an example:

     1    # A-A-P port recipe for Vim 6.1 plus a few patches.
     2    RECIPEVERSION =     1.0
     3
     4    PORTNAME =          vim
     5    LASTPATCH =         003
     6    PORTVERSION =       6.1.$LASTPATCH
     7    MAINTAINER =        Bram@vim.org
     8
     9    CATEGORIES =        editors
    10    PORTCOMMENT =       Vim - Vi IMproved, the text editor
    11    PORTDESCR << EOF
    12    This is the description for the Vim package.
    13    A very nice editor, backwards compatible to Vi.
    14    You can find all info on http://www.vim.org.
    15            EOF
    16
    17    :recipe {fetch = http://www.a-a-p.org/ports/vim/main.aap}
    18
    19    WRKSRC =            vim61
    20    BUILDCMD =          make
    21    TESTCMD =           make test
    22    INSTALLCMD =        make install DESTDIR=$PKGDIR
    23    PREFIX =            /usr/local
    24
    25    MASTER_SITES ?=     ftp://ftp.vim.org/pub/vim
    26                        ftp://ftp.us.vim.org/pub/vim
    27    PATCH_SITES =       $*MASTER_SITES/patches
    28
    29    DISTFILES =         unix/vim-6.1.tar.bz2
    30
    31    version1 =          `range(1, int(LASTPATCH) + 1)`
    32    PATCHFILES =        6.1.00$*version1
    33
    34    #>>> automatically inserted by "aap makesum" <<<
    35    do-checksum:
    36            :checksum $DISTDIR/vim-6.1.tar.bz2 {md5 = 7fd0f915adc7c0dab89772884268b030}
    37            :checksum $PATCHDISTDIR/6.1.001 {md5 = 97bdbe371953b9d25f006f8b58b53532}
    38            :checksum $PATCHDISTDIR/6.1.002 {md5 = f56455248658f019dcf3e2a56a470080}
    39            :checksum $PATCHDISTDIR/6.1.003 {md5 = 0e000edba66562473a5f1e9b5b269bb8}
    40    #>>> end <<<

Well, that is the longest example we have had so far. Let's go through it from top to bottom.

     1    # A-A-P port recipe for Vim 6.1 plus a few patches.
     2    RECIPEVERSION =     1.0

`RECIPEVERSION` tells Aap what version of Aap this recipe was written for. If in the future the recipe format changes, this line causes Aap to interpret it as Aap version 1.0 would do.

     4    PORTNAME =          vim

Setting `PORTNAME` to the name of the port is what actually triggers Aap to read this recipe as a port recipe. It makes the other settings to be used to set up a whole range of targets and build commands. The result is that you can do `aap install` to install the application, for example. Note that `PORTNAME` does not include the version number.

     5    LASTPATCH =         003
     6    PORTVERSION =       6.1.$LASTPATCH
     7    MAINTAINER =        Bram@vim.org
     8
     9    CATEGORIES =        editors
    10    PORTCOMMENT =       Vim - Vi IMproved, the text editor
    11    PORTDESCR << EOF
    12    This is the description for the Vim package.
    13    A very nice editor, backwards compatible to Vi.
    14    You can find all info on http://www.vim.org.
    15            EOF

In lines 5 to 15 a number of informative items about the port are specified. These are used in various places. `LASTPATCH` is not a standard item, it is used here to only have to define the patchlevel in one place.

    17    :recipe {fetch = http://www.a-a-p.org/ports/vim/main.aap}

The `:recipe` command specifies where to obtain the recipe itself from. We have seen this before, nothing special here.

    19    WRKSRC =            vim61
    20    BUILDCMD =          make
    21    TESTCMD =           make test

The assignments in lines 19 to 21 specify how building is to be done. `WRKSRC` is the directory below which the source files are unpacked. The default is "$PORTNAME-$PORTVERSION". The archive used for Vim uses "vim61" instead, thus this needs to be specified. The "CMD" variables set the commands to be used to build the application. The default is to use Aap. Since Vim uses "make" this needs to be specified.

    22    INSTALLCMD =        make install DESTDIR=$PKGDIR
    23    PREFIX =            /usr/local

Installing a port is done by creating a binary package and installing that package. This makes it possible to copy the package to another system and install it there without the need to compile from sources. Lines 22 and 23 specify how to do a "fake install" with Vim. This copies all the files that are to be installed to a specific directory, so that it is easy to include them in the package. `PREFIX` specifies below which directory Vim installs its files.

    25    MASTER_SITES ?=     ftp://ftp.vim.org/pub/vim
    26                        ftp://ftp.us.vim.org/pub/vim
    27    PATCH_SITES =       $*MASTER_SITES/patches

`MASTER_SITES` and `PATCH_SITES` specify the sites where the Vim files can be downloaded from. The first is for the archives, the second for the patches. Note the use of "$*" in line 27, this causes "/patches" to be appended to each item in `MASTER_SITES` instead of appending it once at the end of the whole list.

    29    DISTFILES =         unix/vim-6.1.tar.bz2

`DISTFILES` is set to the name of the archive to download. This is appended to items in `MASTER_SITES` to form the URL.

    31    version1 =          `range(1, int(LASTPATCH) + 1)`
    32    PATCHFILES =        6.1.00$*version1

Lines 32 and 33 specify the list of patch file names. The Python function "range()" is used, this returns a list of numbers in the specified range (up to and excluding the upper number). Note the user of "int()" to turn the patch number in `LASTPATCH` into an int type, all Aap variables are strings.

for three patch files this could also have been typed, but when the number of patches grows this mechanism is easier. The example only works up to patch number 009. To make it work for numbers from 100 up to 999:

          version1 =          `range(1, 10)`
          version2 =          `range(10, 100)`
          version3 =          `range(100, int(LASTPATCH) + 1)`
          PATCHFILES =        6.1.00$*version1  6.1.0$*version2  6.1.$*version3

    34    #>>> automatically inserted by "aap makesum" <<<
    35    do-checksum:
    36            :checksum $DISTDIR/vim-6.1.tar.bz2 {md5 = 7fd0f915adc7c0dab89772884268b030}
    37            :checksum $PATCHDISTDIR/6.1.001 {md5 = 97bdbe371953b9d25f006f8b58b53532}
    38            :checksum $PATCHDISTDIR/6.1.002 {md5 = f56455248658f019dcf3e2a56a470080}
    39            :checksum $PATCHDISTDIR/6.1.003 {md5 = 0e000edba66562473a5f1e9b5b269bb8}
    40    #>>> end <<<

Finally the "do-checksum" target is defined. This part was not typed, but added to the recipe with `aap makesum`. This is done by the port recipe maintainer, when he has verified that the files are correct. When a user later uses the recipe Aap will check that the checksums match, so that problems with downloading or a cracked distribution file are found and reported.

## Using CVS

The port recipe specifies which source files and patches to download, thus it has to be adjusted for each version. This is good for a stable release, but when you are releasing a new version every day it is a lot of work. Another method is possible when the files are available from a CVS server. Adding these lines to the recipe will do it:

          CVSROOT ?=        :pserver:anonymous@vim.cvs.sf.net:/cvsroot/vim
          CVSMODULES =      vim
          CVSTAG =          vim-6-1-$LASTPATCH

The first line specifies the cvsroot to use. This is specific for the cvs program. `CVSMODULES` is the name of the module to checkout. Mostly it is just one name, but you can specify several. Specifying `CVSTAG` is optional. If it is defined, like here, a specific version of the application is obtained. When it is omitted the latest version is obtained.

Much more about the port recipe can be found in Chapter 22, Porting an Application.

Prev | Up | Next
Chapter 10. Commands in a Pipe | Contents | Part II. User Manual