.. _rulefile: 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 .. 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. .. _make-prereq-types: https://www.gnu.org/software/make/manual/make.html#Prerequisite-Types 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: .. code-block:: make $(STATEDIR)/.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: .. code-block:: make $(_SOURCE): @$(call targetinfo) @$(call get, ) extract Stage Default Rule ^^^^^^^^^^^^^^^^^^^^^^^^^^ If the *extract* stage is omitted, PTXdist runs instead: .. code-block:: make $(STATEDIR)/.extract: @$(call targetinfo) @$(call clean, $(_DIR)) @$(call extract, ) @$(call patchin, ) @$(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 :ref:`adding_src_autoconf_templates` for further details. prepare Stage Default Rule ^^^^^^^^^^^^^^^^^^^^^^^^^^ If the *prepare* stage is omitted, PTXdist runs a default stage rule, which looks like this: .. code-block:: make $(STATEDIR)/.prepare: @$(call targetinfo) @$(call world/prepare, ) @$(call touch) What ``world/prepare`` does depends on some variable settings. If the package’s rule file defines ``_CONF_TOOL`` to ``NO``, this stage is simply does nothing. All rules files can create the ``_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 ``_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: .. code-block:: sh cd ${_DIR}/${_SUBDIR} && \ ${_PATH} ${_CONF_ENV} \ ./configure ${_CONF_OPT} The ``_CONF_OPT`` should at least be defined to ``$(CROSS_AUTOCONF_USR)``. If the package’s rule file defines ``_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: .. code-block:: sh cd ${_DIR} && \ ${_PATH} ${_CONF_ENV} \ cmake ${_CONF_OPT} The ``_CONF_OPT`` should at least be defined to ``$(CROSS_CMAKE_USR)`` or ``$(CROSS_CMAKE_ROOT)``. If the package’s rule file defines ``_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: .. code-block:: sh cd ${_DIR} && \ ${_PATH} ${_CONF_ENV} \ qmake ${_CONF_OPT} The ``_CONF_OPT`` should at least be defined to ``$(CROSS_QMAKE_OPT)``. compile Stage Default Rule ^^^^^^^^^^^^^^^^^^^^^^^^^^ If the *compile* stage is omitted, PTXdist runs instead: .. code-block:: make $(STATEDIR)/.compile: @$(call targetinfo) @$(call world/compile, ) @$(call touch) Except in some corner cases, ``world/compile`` expands to something like this: .. code-block:: sh cd ${_DIR} && \ ${_PATH} ${_MAKE_ENV} \ ${MAKE} ${_MAKE_OPT} ${PARALLELMFLAGS} The variables that are used here are described in the :ref:`Compile Stage` section of the variable reference. ``PARALLELMFLAGS`` can be used in custom compile stages. The default stage uses the same value if ``_MAKE_PAR`` is set to ``YES``. install Stage Default Rule ^^^^^^^^^^^^^^^^^^^^^^^^^^ If the *install* stage is omitted, PTXdist runs instead: .. code-block:: make $(STATEDIR)/.install: @$(call targetinfo) @$(call world/install, ) @$(call touch) Except in some corner cases, ``world/install`` expands to something like this: .. code-block:: sh cd ${_DIR} && \ ${_PATH} ${_MAKE_ENV} \ ${MAKE} ${_INSTALL_OPT} The variables that are used here are described in the :ref:`Install Stage` section of the variable reference. At the end of this stage, all relevant files must be installed in the :ref:`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 :ref:`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 :ref:`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 :ref:`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 :ref:`reference_macros` 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. Skipping a Stage ~~~~~~~~~~~~~~~~ For the case that a specific stage should be really skipped, an empty rule must be provided: .. code-block:: make $(STATEDIR)/.: @$(call targetinfo) @$(call touch) Replace the by ``get``, ``extract``, ``prepare``, ``compile``, ``install`` or ``targetinstall``.