5.3. Rule File Layout

Each rule file provides PTXdist with the required steps (in PTXdist called stages) to be done on a per package base:

  1. get

  2. extract

    • extract.post

  3. prepare

  4. compile

  5. install

    • install.pack

    • install.unpack

    • install.post

  6. targetinstall

    • targetinstall.post

  7. clean

Note

Host, image and cross packages don’t need to install anything in the target file system. Therefore, PTXdist only respects the targetinstall and targetinstall.post stages for packages whose name doesn’t start with host-, image-, or cross-.

When you want to depend on the output of a certain image package, you can usually use its image name as an additional prerequisite in your make rule for the dependent stage.

Default stage rules

As for most packages these steps can be done in a default way, PTXdist provides generic rules for each package. If a package’s rule file does not provide a specific stage rule, the default stage rule will be used instead.

Important

Omitting one of the stage rules does not mean that PTXdist skips this stage! In this case the default stage rule is used instead.

get Stage Default Rule

If the get stage is omitted, PTXdist runs instead:

$(STATEDIR)/<pkg>.get:
    @$(call targetinfo)
    @$(call touch)

Which means this step is skipped.

If the package is an archive that must be downloaded from the web, the following rule must exist in this case:

$(<PKG>_SOURCE):
    @$(call targetinfo)
    @$(call get, <PKG>)

extract Stage Default Rule

If the extract stage is omitted, PTXdist runs instead:

$(STATEDIR)/<pkg>.extract:
    @$(call targetinfo)
    @$(call clean, $(<PKG>_DIR))
    @$(call extract, <PKG>)
    @$(call patchin, <PKG>)
    @$(call touch)

Which means a current existing directory of this package will be removed, the archive gets freshly extracted again and (if corresponding patches are found) patched.

extract.post Stage Default Rule

This is an optional stage, mainly used to somehow prepare a package for the next prepare stage step. This stage can be used to generate a configure script out of an autotoolized configure.ac file for example. This separation from the extract stage is useful to be able to extract a package for a quick look into the sources without the need to build all the autotools first. The autotoolized PTXdist templates makes use of this feature. Refer Creating Autotools based Packages for further details.

prepare Stage Default Rule

If the prepare stage is omitted, PTXdist runs a default stage rule, which looks like this:

$(STATEDIR)/<pkg>.prepare:
    @$(call targetinfo)
    @$(call world/prepare, <PKG>)
    @$(call touch)

What world/prepare does depends on some variable settings.

If the package’s rule file defines <PKG>_CONF_TOOL to NO, this stage is simply does nothing.

All rules files can create the <PKG>_CONF_ENV variable and should define it at least to $(CROSS_ENV) (the default) if the prepare stage is used.

If the package’s rule file defines <PKG>_CONF_TOOL to autoconf (FOO_CONF_TOOL = autoconf for our foo example), PTXdist treats this package as an autotoolized package and world/prepare expands to something like this:

cd ${<PKG>_DIR}/${<PKG>_SUBDIR} && \
    ${<PKG>_PATH} ${<PKG>_CONF_ENV} \
    ./configure ${<PKG>_CONF_OPT}

The <PKG>_CONF_OPT should at least be defined to $(CROSS_AUTOCONF_USR).

If the package’s rule file defines <PKG>_CONF_TOOL to cmake (FOO_CONF_TOOL = cmake for our foo example), PTXdist treats this package as a cmake based package and world/prepare expands to something like this:

cd ${<PKG>_DIR} && \
    ${<PKG>_PATH} ${<PKG>_CONF_ENV} \
    cmake ${<PKG>_CONF_OPT}

The <PKG>_CONF_OPT should at least be defined to $(CROSS_CMAKE_USR) or $(CROSS_CMAKE_ROOT).

If the package’s rule file defines <PKG>_CONF_TOOL to qmake (FOO_CONF_TOOL = qmake for our foo example), PTXdist treats this package as a qmake based package and world/prepare expands to something like this:

cd ${<PKG>_DIR} && \
    ${<PKG>_PATH} ${<PKG>_CONF_ENV} \
    qmake ${<PKG>_CONF_OPT}

The <PKG>_CONF_OPT should at least be defined to $(CROSS_QMAKE_OPT).

compile Stage Default Rule

If the compile stage is omitted, PTXdist runs instead:

$(STATEDIR)/<pkg>.compile:
    @$(call targetinfo)
    @$(call world/compile, <PKG>)
    @$(call touch)

Except in some corner cases, world/compile expands to something like this:

cd ${<PKG>_DIR} && \
    ${<PKG>_PATH} ${<PKG>_MAKE_ENV} \
    ${MAKE} ${<PKG>_MAKE_OPT} ${PARALLELMFLAGS}

The variables that are used here are described in the Compile Stage section of the variable reference.

PARALLELMFLAGS can be used in custom compile stages. The default stage uses the same value if <PKG>_MAKE_PAR is set to YES.

install Stage Default Rule

If the install stage is omitted, PTXdist runs instead:

$(STATEDIR)/<pkg>.install:
    @$(call targetinfo)
    @$(call world/install, <PKG>)
    @$(call touch)

Except in some corner cases, world/install expands to something like this:

cd ${<PKG>_DIR} && \
    ${<PKG>_PATH} ${<PKG>_MAKE_ENV} \
    ${MAKE} ${<PKG>_INSTALL_OPT}

The variables that are used here are described in the Install Stage section of the variable reference.

At the end of this stage, all relevant files must be installed in the package install directory.

install.pack Stage Default Rule

The install.pack should not be overwritten. It consists of two steps. The first is, to make the installed files relocatable. This is necessary to ensure that everything works correctly once the files are copied to sysroot in install.post. If creating pre-built archives is enabled, then the second step is to create the archive for the package.

install.unpack Stage Default Rule

The install.unpack is only executed if using pre-built archives is enabled. In this case, it replaces all previous stages. Here, the pre-built is extract.

install.post Stage Default Rule

The install.post is mostly internal. Few packages need to customize it. It copies all files from the package install directory into the corresponding sysroot.

targetinstall Stage Default Rule

There is no default rule for a package’s targetinstall state. PTXdist has no idea what is required on the target at run-time. This stage is up to the developer only. Refer to section Rule File Macro Reference for further info on how to select files to be included in the target’s root filesystem.

targetinstall.post Stage Default Rule

The targetinstall.post stage does nothing by default. It can be used to do some work after the targetinstall stage.

clean Stage Default Rule

The clean stage is only executed when calling ptxdist clean <package>.

The default clean stage calls the world/clean macro:

$(STATEDIR)/<pkg>.clean:
    @$(call targetinfo)
    @$(call world/clean, <PKG>)

This will invalidate all stages of the package, and remove all its existing build artefacts:

  • <PKG>_DIR, and $(<PKG>_DIR)-build for out-of-tree builds,

  • <PKG>_PKGDIR (i.e., usually $(PKGDIR)/$(<PKG>))

  • the pre-built archive in PKGDIR (if enabled)

  • the files that the package has installed into the respective sysroot folder (platform-example/sysroot-{target,host,cross}/),

  • for target packages, any output of the package’s targetinstall stage built by the following macros:

    • opkg packages defined by install_init and install_finish,

    • any files installed into the target root file system (platform-example/root/) via install_copy, install_glob, install_alternative, install_tree and similar,

    • images installed to the image directory by ptx/install-image and ptx/install-image-link

It will not remove any input files like patches or downloaded sources or config files, nor will it remove any pre-built archives from PTXCONF_PROJECT_DEVPKGDIR.

Skipping a Stage

For the case that a specific stage should be really skipped, an empty rule must be provided:

$(STATEDIR)/<pkg>.<stage_to_skip>:
    @$(call targetinfo)
    @$(call touch)

Replace the <stage_to_skip> by get, extract, prepare, compile, install or targetinstall.