The reference manual has gotten quite big now. Split it up into three files so it is easier to navigate for editing.
No further change to the content. Signed-off-by: Roland Hieber <[email protected]> --- doc/ref_make_macros.inc | 834 ++++++++++++++++++ doc/ref_make_variables.inc | 444 ++++++++++ doc/ref_manual.rst | 1542 +--------------------------------- doc/ref_rule_file_layout.inc | 261 ++++++ 4 files changed, 1542 insertions(+), 1539 deletions(-) create mode 100644 doc/ref_make_macros.inc create mode 100644 doc/ref_make_variables.inc create mode 100644 doc/ref_rule_file_layout.inc diff --git a/doc/ref_make_macros.inc b/doc/ref_make_macros.inc new file mode 100644 index 000000000000..101f53c8d56c --- /dev/null +++ b/doc/ref_make_macros.inc @@ -0,0 +1,834 @@ +.. _reference_macros: + +Rule File Macro Reference +------------------------- + +Rules files in PTXdist are using macros to get things work. Its highly +recommended to use these macros instead of doing something by ourself. Using these +macros is portable and such easier to maintain in the case a project should be +upgraded to a more recent PTXdist version. + +This chapter describes the predefined macros in PTXdist and their usage. + +Whenever one of these macros installs something to the target's root filesystem, +it also accepts user and group IDs which are common in all filesystems Linux +supports. These IDs can be given as numerical values and as text strings. +In the case text strings are given PTXdist converts them into the +corresponding numerical value based on the BSP local files :file:`passwd` and :file:`group`. +If more than one file with these names are present in the BSP PTXdist follows +its regular rules which one it prefers. + +Many paths shown here contains some parts in angle brackets. These have +special meanings in this document. + +**<platform>** + The name of a platform. Corresponds to the variable + ``PTXCONF_PLATFORM`` +**<platform-src>** + The directory where the platform is defined. Corresponds to the variable + ``PTXDIST_PLATFORMCONFIGDIR`` +**<platform-dir>** + Concatenated directory name with a leading *platform-* and the name of the + selected platform name, e.g. <platform>. If the name of the currently active + platform is *foo*, the final directory name is *platform-foo*. + Corresponds to the variable ``PTXDIST_PLATFORMDIR`` + +.. note:: The list of supported macros is not complete yet. + +targetinfo +~~~~~~~~~~ + +Usage: + +.. code-block:: make + + $(call targetinfo) + +Gives a feedback, what build *stage* is just started. That's why it +should always be the first call for each *stage*. For the package +*foo* and the *compile stage* it will output: + +.. code-block:: bash + + -------------------- + target: foo.compile + -------------------- + +touch +~~~~~~ + +Usage: + +.. code-block:: make + + $(call touch) + +Gives a feedback, what build *stage* is just finished. That's why it +should always be the last call for each *stage*. For the package +*foo* and the *compile stage* it will output: + +.. code-block:: bash + + finished target foo.compile + +clean +~~~~~ + +Usage: + +.. code-block:: make + + $(call clean, <directory path>) + +Removes the given directory ``<directory path>`` + +.. _install_copy: + +world/get, world/extract, world/prepare, world/compile, world/install +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Usage: + +.. code-block:: make + + $(call world/get, <PKG>) + +The same for all other macros. These are the default build commands for the +corresponding stages. For more details see the documentation of the default +stages below. + +compile +~~~~~~~ + +Usage: + +.. code-block:: make + + $(call compile, <PKG>, <build arguments>) + +This macro is very similar to ``world/compile``. The only differences is +that is uses the specified ``build arguments`` instead of +``<PKG>_MAKE_OPT``. This is usefull if ``make`` needs to be called more +than once in the compile stage. + +world/execute, execute +~~~~~~~~~~~~~~~~~~~~~~ + +Usage: + +.. code-block:: make + + $(call execute, <PKG>, <command with arguments>) + $(call world/execute, <PKG>, <command with arguments>) + +These macros make it possible to execute arbitrary commands during the +build stages. This is usefull because the environment is identical to the +default build commands ``world/*``. + +``world/execute`` also handles the generic setup handled in the current +build stage. For ``prepare`` this means that, for out ot tree builds, the +build directory is deleted prior to executing the specified command. +For ``install`` the package directory is deleted. + +When ``--verbose`` is used then the full command is logged. With +``--quiet`` both stdout and stderr are redirected to the logfile. + +install_copy +~~~~~~~~~~~~~ + +Usage: + +.. code-block:: make + + $(call install_copy, <package>, <UID>, <GID>, <permission>, <source> [, <dest> [, <strip> ]]) + +Installs given file or directory into: + +* the project's ``<platform-dir>/root/`` +* an ipkg/opkg packet in the project's ``<platform-dir>/packages/`` + +Some of the parameters have fixed meanings: + +**<package>** + Name of the IPKG/OPKG the macro should work on +**<UID>** + User ID the file should use in the target's root filesystem +**<GID>** + Group ID the file should use in the target's root filesystem +**<permission>** + Permission (in an octal value) the file should use in the target's root filesystem + +The remaining parameters vary with the use case: + +The ``<source>`` parameter can be: + +* a directory path that should be created in the target's root filesystem. + In this case the <destination> must be omitted. + The given path must always start with a ``/`` and means the root + of the target's filesystem. +* an absolute path to a file that should be copied to the target's root + filesystem. To avoid fixed paths, all packages are providing the + <PKG>_DIR variable. So, this parameter in our + *foo* example package can be a ``$(FOO_DIR)/foo``. +* a minus sign (``-``). PTXdist uses the <destination> + parameter in this case to locate the file to copy from. + The <destination> is uses a path relative to the :ref:`package install + directory<pkg_pkgdir>`. This only works if the package uses the default + or a similar *install* stage. For our *foo* example used source file is + ``<platform-dir>/packages/foo-1.1.0/<destination>``. + +The ``<dest>`` parameter can be: + +* omitted if a directory in target's root filesystem should be created. + For this case the directory to be created is in the <source> parameter. +* an absolute path and filename with its root in target's root filesystem. + It must start with a slash (``//``). If also the <source> + parameter was given, the file can be renamed while copying. + If the <source> parameter was given as a minus + sign (``-``) the <destination> is also used to + locate the source. For our *foo* example package if we give + <destination> as ``/usr/bin/foo``, PTXdist + copies the file ``<platform-dir>/packages/foo-1.1.0/usr/bin/foo`` + +The ``<strip>`` is a complete optional parameter to prevent +this macro from the regular stripping process it does on files. Most of the cases +stripping debug information from files is intended. But some kind of files getting +destroyed when this stripping happens to them. One example is a Linux kernel module. +If it gets stripped, it can't be loaded into the kernel anymore. + +**full strip** + fully strip the file while installing when this parameter is **y** or not + given at all (default case). +**partially strip** + only strips real debug information from the file when this parameter is + **k**. Useful to keep Linux kernel module loadable at run-time +**no strip** + preserve the file from being stripped when this parameter is one of the + following: **0**, **n**, **no**, **N** or **NO**. + +Due to the complexity of this macro, here are some usage examples: + +Create a directory in the root filesystem: + +.. code-block:: make + + $(call install_copy, foo, 0, 0, 0755, /home/user-foo) + +Copy a file from the package build directory to the root filesystem: + +.. code-block:: make + + $(call install_copy, foo, 0, 0, 0755, $(FOO_DIR)/foo, /usr/bin/foo) + +Copy a file from the package build directory to the root filesystem and rename +it: + +.. code-block:: make + + $(call install_copy, foo, 0, 0, 0755, $(FOO_DIR)/foo, /usr/bin/bar) + +Copy a file from the package install directory to the root filesystem: + +.. code-block:: make + + $(call install_copy, foo, 0, 0, 0755, -, /usr/bin/foo) + +.. _install_tree,reference: + +install_tree +~~~~~~~~~~~~ + +Usage: + +.. code-block:: make + + $(call install_tree, <package>, <UID>, <GID>, <source dir>, <destination dir>) + +Installs the whole directory tree with all files from the given directory into: + +* the project's ``<platform-dir>/root/`` +* an ipkg packet in the project's ``<platform-dir>/packages/`` + +Some of the parameters have fixed meanings: + +**<package>** + Name of the IPKG/OPKG the macro should work on +**<UID>** + User ID the directories and files should use in the target's root filesystem + or ``-`` to keep the UID from the source tree +**<GID>** + Group ID the directories and files should use in the target's root filesystem + or ``-`` to keep the GID from the source tree +**<source dir>** + This is the path to the tree of directories and files to be installed. It can + be ``-`` to use the package directory of the current package instead +**<destination dir>** + The basename of the to-be-installed tree in the root filesystem + +Note: This installation macro + +* uses the same permission flags in the destination dir as found + in the source dir. This is valid for directories and regular files +* skips all directories with names like ``.svn``, ``.git``, ``.pc`` and + ``CVS`` in the source directory + +Examples: + +Install the whole tree found in ``/home/jbe/foo`` to the root filesystem +at location ``/usr/share/bar``. + +.. code-block:: make + + $(call install_tree, foo, 0, 0, /home/jbe/foo, /usr/share/bar) + +Install all files from the tree found in the current package FOO to the root +filesystem at location ``/usr/share/bar``. + +.. code-block:: make + + $(call install_tree, foo, 0, 0, -, /usr/share/bar) + +If the current package is ``foo-1.0`` the base path for the directory tree +will be ``$(PKGDIR)/foo-1.0/usr/share/bar``. + +install_alternative_tree +~~~~~~~~~~~~~~~~~~~~~~~~ + +Usage: + +.. code-block:: make + + $(call install_alternative_tree, <package>, <UID>, <GID>, <destination dir>) + +Installs the whole source directory tree with all files from the given directory into: + +* the project's ``<platform-dir>/root/`` +* an ipkg packet in the project's ``<platform-dir>/packages/`` + +The ``<destination dir>`` is used like in the ``install_alternative`` to let +PTXdist search in the same directories and order for the given directory. + +Some of the parameters have fixed meanings: + +**<package>** + Name of the IPKG/OPKG the macro should work on +**<UID>** + User ID the directories and files should use in the target's root filesystem + or ``-`` to keep the UID from the source +**<GID>** + Group ID the directories and files should use in the target's root + filesystem or ``-`` to keep the GID from the source +**<destination dir>** + The basename of the to-be-installed tree in the root filesystem + +.. note:: This installation macro + + * uses the same permission flags in the destination dir as found in the source + dir. This is valid for directories and regular files + * skips all directories with names like ``.svn``, ``.git``, ``.pc`` and ``CVS`` + in the source directory + +Examples: + +Install the whole tree found in project's ``projectroot/usr/share/bar`` +to the root filesystem at location ``/usr/share/bar``. + +.. code-block:: make + + $(call install_alternative_tree, foo, 0, 0, /usr/share/bar) + +To install nothing, use a symlink to ``/dev/null`` instead of the base +directory. See :ref:`install_alternative` for more details. + +.. _install_alternative: + +install_alternative +~~~~~~~~~~~~~~~~~~~ + +Usage: + +.. code-block:: make + + $(call install_alternative, <package>, <UID>, <GID>, <permission>, <destination>) + +Installs given files or directories into: + +* the project's ``<platform-dir>/root/`` +* an ipkg/opkg packet in the project's ``<platform-dir>/packages/`` + +The base parameters and their meanings: + +**<package>** + Name of the IPKG/OPKG the macro should work on +**<UID>** + User ID the file should use in the target's root filesystem +**<GID>** + Group ID the file should use in the target's root filesystem +**<permission>** + Permission (in an octal value) the file should use in the target's root filesystem + +The parameter <destination> is meant as an absolute path +and filename in target's root filesystem. PTXdist searches for the source +of this file in: + +* the local project +* in the used platform +* PTXdist's install path +* in the current package + +As this search algorithm is complex, here an example for the file +``/etc/foo`` in package ``FOO``. PTXdist will search for this +file in the following order: + +* project's directory ``projectroot.<platform>/etc/foo`` +* project's directory ``projectroot/etc/foo.<platform>`` +* platform's directory ``<platform-src>/projectroot/etc/foo.<platform>`` +* project's directory ``projectroot/etc/foo`` +* platform's directory ``<platform-src>/projectroot/etc/foo`` +* ptxdist's directory ``projectroot/etc/foo`` +* package's directory ``$(FOO_PKGDIR)/etc/foo`` +* package's directory ``$(FOO_DIR)/etc/foo`` + +The generic rules are looking like the following: + +* ``$(PTXDIST_WORKSPACE)/projectroot$(PTXDIST_PLATFORMSUFFIX)/etc/foo`` +* ``$(PTXDIST_WORKSPACE)/projectroot/etc/foo$(PTXDIST_PLATFORMSUFFIX)`` +* ``$(PTXDIST_PLATFORMCONFIGDIR)/projectroot/etc/foo$(PTXDIST_PLATFORMSUFFIX)`` +* ``$(PTXDIST_WORKSPACE)/projectroot/etc/foo`` +* ``$(PTXDIST_PLATFORMCONFIGDIR)/projectroot/etc/foo`` +* ``$(PTXDIST_TOPDIR)/projectroot/etc/foo`` +* ``$(FOO_PKGDIR)/etc/foo`` +* ``$(FOO_DIR)/etc/foo`` + +Note: You can get the current values for the listed variables above via running +PTXdist with the ``print`` parameter: + +.. code-block:: bash + + $ ptxdist print PTXDIST_PLATFORMSUFFIX + +``install_alternative`` is used by upstream PTXdist packages to install +config files. In some rare use-cases the file should not be installed at +all. For example if the config file is generated at runtime or provided by +a special configuration package. This is possible by creating a symlink to +``/dev/null`` instead of a file at one of the locations described above. +PTXdist skips installing the file if it detects such a symlink. + +install_link +~~~~~~~~~~~~ + +Usage: + +.. code-block:: make + + $(call install_link, <package>, <point to>, <where>) + +Installs a symbolic link into: + +* the project's ``<platform-dir>/root/`` +* an ipkg/opkg packet in the project's ``<platform-dir>/packages/`` + +The parameters and their meanings: + +**<package>** + Name of the IPKG/OPKG the macro should work on +**<point to>** + Path and name the link should point to. Note: This macro rejects absolute + paths. If needed use relative paths instead. +**<where>** + Path and name of the symbolic link. + +A few usage examples. + +Create a symbolic link as ``/usr/lib/libfoo.so`` pointing to +``libfoo.so.1.1.0`` in the same directory: + +.. code-block:: make + + $(call install_link, foo, libfoo.so.1.1.0, /usr/lib/libfoo.so) + +Create a symbolic link as ``/usr/bin/foo`` pointing to ``/bin/bar``: + +.. code-block:: make + + $(call install_link, foo, ../../bin/bar, /usr/bin/foo) + +.. _install_archive: + +install_archive +~~~~~~~~~~~~~~~ + +Usage: + +.. code-block:: make + + $(call install_archive, <package>, <UID>, <GID>, <archive> , <base path>) + +Installs archives content into: + +* the project's ``<platform-dir>/root/`` +* an ipkg/opkg packet in the project's ``<platform-dir>/packages/`` + +All parameters have fixed meanings: + +**<package>** + Name of the IPKG/OPKG the macro should work on +**<UID>** + User ID all files and directory of the archive should use in the target's + root filesystem. A ``-`` uses the file's/directory's UID in the archive +**<GID>** + Group ID the files and directories should use in the target's root filesystem. + A ``-`` uses the file's/directory's GID in the archive +**<archive>** + Name of the archive to be used in this call. The given path and filename is + used as is +**<base path>** + Base path component in the root filesystem the archive should be extracted + to. Can be just ``/`` for root. + +install_glob +~~~~~~~~~~~~ + +Usage: + +.. code-block:: make + + $(call install_glob, <package>, <UID>, <GID>, <source dir>, <destination dir>, <yglob>, <nglob>[, <strip>]) + +Installs parts of a directory tree with all files from the given directory +into: + +* the project's ``<platform-dir>/root/`` +* an ipkg packet in the project's ``<platform-dir>/packages/`` + +Some of the parameters have fixed meanings: + +**<package>** + Name of the IPKG/OPKG the macro should work on +**<UID>** + User ID the directories and files should use in the target's root filesystem + or ``-`` to keep the UID from the source tree +**<GID>** + Group ID the directories and files should use in the target's root filesystem + or ``-`` to keep the GID from the source tree +**<source dir>** + This is the path to the tree of directories and files to be installed. It can + be ``-`` to use the package directory of the current package instead +**<destination dir>** + The basename of the to-be-installed tree in the root filesystem +**<yglob>** + A list of pathname patterns. All files or directories that match _any_ + pattern in the list are installed. Note: the patterns must match the + whole absolute path, e.g. ``*/foo``. An empty list is equivalent to a + pattern that matches all files. +**<nglob>** + Like ``<yglob>`` but any matching files or directories will not be + installed. For directories, this includes the whole contents of the + directory. + +Except for the pathname patterns, this command works like ``install_tree``. +The ``<yglob>`` and ``<nglob>`` patterns are combined: Only files that +match ``<yglob>`` and do not match ``<nglob>`` are installed. + +Examples: + +Install all shared libraries found in ``$(FOO_PKGDIR)/usr/lib/foo`` except +libbar.so + +.. code-block:: make + + $(call install_glob, foo, 0, 0, -, /usr/lib/foo, *.so, */libbar.so) + +install_lib +~~~~~~~~~~~ + +Usage: + +.. code-block:: make + + $(call install_lib, <package>, <UID>, <GID>, <permission>, <libname>) + +Installs the shared library <libname> into the root filesystem. + +* the project's ``<platform-dir>/root/`` +* an ipkg/opkg packet in the project's ``<platform-dir>/packages/`` + +The parameters and their meanings: + +**<package>** + Name of the IPKG/OPKG the macro should work on +**<UID>** + User ID the file should use in the target's root filesystem +**<GID>** + Group ID the directories and files should use in the target's root filesystem +**<permission>** + Permission (as an octal value) the library should use in the target's root + filesystem (mostly 0644) +**<libname>** + Basename of the library without any extension and path + +The ``install_lib`` macro searches for the library at the most +common directories ``/lib`` and ``/usr/lib``. And it searches always +in the package's corresponding directory in ``<platform-dir>/packages/``. +It also handles all required links to make the library work at run-time. + +An example. + +Lets assume the package 'foo-1.0.0' has installed the library ``libfoo`` into +its ``<platform-dir>/packages/foo-1.0.0`` at: + +* the lib: ``<platform-dir>/packages/foo-1.0.0/usr/lib/libfoo1.so.0.0.0`` +* first link: ``<platform-dir>/packages/foo-1.0.0/usr/lib/libfoo1.so.0`` +* second link: ``<platform-dir>/packages/foo-1.0.0/usr/lib/libfoo1.so`` + +.. note:: The second link is only needed for the linker at build-time to + resolve ``-lfoo1``. It is not needed at run-time so ``install_lib`` will + skip it. + +To install this library and its corresponding link, the following line does the job: + +.. code-block:: make + + $(call install_lib, foo, 0, 0, 0644, libfoo1) + +Note: The package's install stage must be 'DESTDIR' aware to be able to make +it install its content into the corresponding packages directory (in our example +``<platform-dir>/packages/foo-1.0.0/`` here). + +install_replace +~~~~~~~~~~~~~~~ + +Usage: + +.. code-block:: make + + $(call install_replace, <package>, <filename>, <placeholder>, <value>) + +Replace placeholder with value in a previously installed file. + +The parameters and their meanings: + +**<package>** + Name of the IPKG/OPKG the macro should work on +**<filename>** + Absolute filepath in target root filesystem +**<placeholder>** + A string in the file which should be replaced. Usually some uppercase word + surrounded by @ signs +**<value>** + The value which should appear in the root filesystem instead of the + placeholder, could be some PTXCONF variable + +The ``install_replace`` macro can be used in targetinstall stage to adapt +some template and replace strings with content from menu variables or other +sources. For example look at the timezone you set in the ptxdist menu. An +``install_replace`` call in ``rules/timezone.make`` replaces the string +``@TIMEZONE@`` in the file ``/etc/timezone`` in root filesystem with the +content of the menu variable ``PTXCONF_TIMEZONE_LOCALTIME``. The file must +be installed with some other ``install_*`` command before +``install_replace`` can be used. A typical call would look like this: + +.. code-block:: make + + $(STATEDIR)/timezone.targetinstall: + ... + @$(call install_replace, timezone, /etc/timezone, @TIMEZONE@, \ + $(PTXCONF_TIMEZONE_LOCALTIME)) + +.. _param_macros: + +.. _ptxEndis: + +ptx/endis +~~~~~~~~~ + +To convert the state (set/unset) of a variable into an ``enable/disable`` +string use the ``ptx/endis`` macro. +If the given <variable> is set this macro expands to +the string ``enable``, if unset to ``disable`` instead. + +Usage: + +.. code-block:: none + + --$(call ptx/endis, <variable>)-<parameter> + +An example: + +.. code-block:: make + + FOO_CONF_OPT += --$(call ptx/endis,FOO_VARIABLE)-something + +Depending on the state of FOO_VARIABLE this line results into + +.. code-block:: make + + FOO_CONF_OPT += --enable-something (if FOO_VARIABLE is set) + FOO_CONF_OPT += --disable-something (if FOO_VARIABLE is unset) + +Refer :ref:`ptxDisen` for the opposite string expansion. + +.. _ptxDisen: + +ptx/disen +~~~~~~~~~ + +To convert the state (set/unset) of a variable into a ``disable/enable`` +string use the ``ptx/disen`` macro. +If the given <variable> is set this macro expands to +the string ``disable``, if unset to ``enable`` instead. + +Usage: + +.. code-block:: none + + --$(call ptx/disen, <variable>)-<parameter> + +An example: + +.. code-block:: make + + FOO_CONF_OPT += --$(call ptx/disen,FOO_VARIABLE)-something + +Depending on the state of FOO_VARIABLE this line results into + +.. code-block:: make + + FOO_CONF_OPT += --disable-something (if FOO_VARIABLE is set) + FOO_CONF_OPT += --enable-something (if FOO_VARIABLE is unset) + +Refer :ref:`ptxEndis` for the opposite string expansion. + +ptx/wwo +~~~~~~~ + +To convert the state (set/unset) of a variable into a ``with/without`` +string use the ``ptx/wwo`` macro. +If the given <variable> is set this macro expands to +the string ``with``, if unset to ``without`` instead. + +Usage: + +.. code-block:: none + + --$(call ptx/wwo, <variable>)-<parameter> + +An example: + +.. code-block:: make + + FOO_CONF_OPT += --$(call ptx/wwo,FOO_VARIABLE)-something + +Depending on the state of FOO_VARIABLE this line results into + +.. code-block:: make + + FOO_CONF_OPT += --with-something (if FOO_VARIABLE is set) + FOO_CONF_OPT += --without-something (if FOO_VARIABLE is unset) + +ptx/ifdef +~~~~~~~~~ + +To convert the state (set/unset) of a variable into one of two strings use the +``ptx/ifdef`` macro. +If the given <variable> is set this macro expands to +the first given string, if unset to the second given string. + +Usage: + +.. code-block:: make + + --with-something=$(call ptx/ifdef, <variable>, <first-string>, <second-string) + +An example: + +.. code-block:: make + + FOO_CONF_OPT += --with-something=$(call ptx/ifdef,FOO_VARIABLE,/usr,none) + +Depending on the state of FOO_VARIABLE this line results into + +.. code-block:: make + + FOO_CONF_OPT += --with-something=/usr (if FOO_VARIABLE is set) + FOO_CONF_OPT += --with-something=none (if FOO_VARIABLE is unset) + +ptx/truefalse +~~~~~~~~~~~~~ + +To convert the state (set/unset) of a variable into a ``true/false`` +string use the ``ptx/truefalse`` macro. +If the given <variable> is set this macro expands to +the string ``true``, if unset to ``false`` instead. + +Usage: + +.. code-block:: none + + -Dwith-something=$(call ptx/truefalse,<variable>) + +An example: + +.. code-block:: make + + FOO_CONF_OPT += -Dwith-something=$(call ptx/truefalse,<variable>) + +Depending on the state of FOO_VARIABLE this line results into + +.. code-block:: make + + FOO_CONF_OPT += -Dwith-something=true (if FOO_VARIABLE is set) + FOO_CONF_OPT += -Dwith-something=false (if FOO_VARIABLE is unset) + +ptx/get-alternative +~~~~~~~~~~~~~~~~~~~ + +This macro can be used to find files or directories in the BSP and PTXdist. +There are two arguments, **prefix** and **file**. The search path is very +similar to :ref:`install_alternative`. The first existing location of the +following paths is returned: + +* ``$(PTXDIST_WORKSPACE)/$(prefix)$(PTXDIST_PLATFORMSUFFIX)/$(file)`` +* ``$(PTXDIST_WORKSPACE)/$(prefix)/$(file)$(PTXDIST_PLATFORMSUFFIX)`` +* ``$(PTXDIST_PLATFORMCONFIGDIR)/$(prefix)/$(file)$(PTXDIST_PLATFORMSUFFIX)`` +* ``$(PTXDIST_WORKSPACE)/$(prefix)/$(file)`` +* ``$(PTXDIST_PLATFORMCONFIGDIR)/$(prefix)/$(file)`` +* ``$(PTXDIST_TOPDIR)/$(prefix)/$(file)`` + + +.. _in_path: + +ptx/in-path +~~~~~~~~~~~ + +This macro can be used to find files or directories in the BSP and PTXdist. +There are two arguments, **path variable** and **file**. The **path +variable** must be a variable name that is available in a shell called by +**make**. The variable must contain a ``:`` separated list of directories. +The **file** will be searched in these directories and the first existing +path is returned. PTXdist defines several variables that can be used here. +The directories are in the usual search order. + +- **PTXDIST_PATH_LAYERS** contains all layers from **PTXDIST_WORKSPACE** + to **PTXDIST_TOPDIR** + +- **PTXDIST_PATH** is like **PTXDIST_PATH_LAYERS** but also contains the + **PTXDIST_PLATFORMCONFIGDIR** for each layer. + +- **PTXDIST_PATH_SCRIPTS**, **PTXDIST_PATH_RULES** and + **PTXDIST_PATH_PLATFORMS** are like **PTXDIST_PATH** with the extra + ``scripts/``, ``rules/`` and ``platforms/`` subdirectory respectively. + +Hint: use the :ref:`print<command_print>` command to get the exact list of +directories for each of these variables. + +.. _in_platformconfigdir: + +ptx/in-platformconfigdir +~~~~~~~~~~~~~~~~~~~~~~~~ + +This macro is only useful with multiple layers. It has one argument +**file**. The **file** is searched for in the platform directory in +all layers in the usual search order. It returns the first existing file. +If none exists it returns ``$(PTXDIST_PLATFORMCONFIGDIR)/$(file)``. This +avoids unexpected errors due to empty variables if a file is missing. diff --git a/doc/ref_make_variables.inc b/doc/ref_make_variables.inc new file mode 100644 index 000000000000..f2b491b407e9 --- /dev/null +++ b/doc/ref_make_variables.inc @@ -0,0 +1,444 @@ +Variables Reference +------------------- + +The following variables are provided by PTXdist to simplify creating +rule files. Every developer should use these variables in every single +line in the **rule file** to avoid any further adaption when external paths +are changed. + +To get their content related to the current project, we can simply run +a: + +:: + + $ ptxdist print PTXDIST_TOPDIR + /usr/local/lib/ptxdist-|ptxdistVendorVersion| + +Replace the ``PTXDIST_TOPDIR`` with one of the other generic variables +PTXdist provides. + +Global Variables +~~~~~~~~~~~~~~~~ + +``PTXDIST_TOPDIR`` + Points always to the installation directory of PTXdist. + +.. _ptxdist_workspace: + +``PTXDIST_WORKSPACE`` + Everything that references ``PTXDIST_WORKSPACE`` will use the active + projects’s folder. + +``PTXDIST_SYSROOT_CROSS`` + ``PTXDIST_SYSROOT_CROSS`` points to a directory tree all cross relevant + executables, libraries and header files are installed to in the current + project. All of the project’s packages built for the host to create data + for the target are searching in this directory tree for their + dependencies (executables, header and library files). Use + ``$(PTXDIST_SYSROOT_CROSS)/bin`` to install executables, + ``$(PTXDIST_SYSROOT_CROSS)/include`` for header files and + ``$(PTXDIST_SYSROOT_CROSS)/lib`` for libraries. + +``PTXDIST_SYSROOT_HOST`` + ``PTXDIST_SYSROOT_HOST`` points to a directory tree all host relevant + executables, libraries and header files are installed to. All project’s + packages built for the host are searching in this directory tree for + their dependencies (executables, header and library files). Use + ``$(PTXDIST_SYSROOT_HOST)/bin`` to install executables, + ``$(PTXDIST_SYSROOT_HOST)/include`` for header files and + ``$(PTXDIST_SYSROOT_HOST)/lib`` for libraries. + +``PTXDIST_SYSROOT_TARGET`` + ``PTXDIST_SYSROOT_TARGET`` points to a directory tree all target + relevant libraries and header files are installed to. All project’s + packages built for the target are searching in this directory tree for + their dependencies (header and library files). These files are for + compile time only (for example to link a target executable against a + target library), not for run-time! Use + ``$(PTXDIST_SYSROOT_TARGET)/include`` for header files and + ``$(PTXDIST_SYSROOT_TARGET)/lib`` for libraries. + +Other useful variables: + +``CROSS_PATH`` + Use to find cross tools. This path must be used to create anything that + depends on the target’s architecture, but needs something running on the + host to do the job. Examples: + + **Creating a UBI image from the target’s root filesystem** + This will need a tool running on the host, but it will create data + or code that runs on or is used on the target + + **Building a library for the target** + If this library needs other resources to be built (other libraries) + its ``configure`` finds the right information in this path. + +``HOST_PATH`` + Used to find host tools. This path must be used to create anything that + doesn't depend on the architecture. + +``ROOTDIR`` + ``ROOTDIR`` points to the root of the target’s root filesystem in the + current project. Used in very rare cases (to create strange packages + based on data in target’s root filesystem for example). + +``PTXCONF_PLATFORM`` + ``PTXCONF_PLATFORM`` expands to the name of the currently selected + platform. This name is used in various file names and paths. + +``PTXDIST_PLATFORMSUFFIX`` + ``PTXDIST_PLATFORMSUFFIX`` expands to the name of the currently selected + platform, but with a leading dot. This is used in various files PTXdist + should search for. + +.. _ptxdist_platformconfigdir: + +``PTXDIST_PLATFORMCONFIGDIR`` + ``PTXDIST_PLATFORMCONFIGDIR`` points to the directory tree of the + currently selected platform. This path is used in various search + functions. + +``PTXDIST_PLATFORMDIR`` + ``PTXDIST_PLATFORMDIR`` points to the directory build tree of the + currently selected platform. + +``PACKAGES``, ``PACKAGES-y``, ``PACKAGES-m`` + ``PACKAGES`` is a list of space-separated lowercase package names that are + built and installed during the PTXdist build run, and installed into the + target root filesystem when building images. + + The ``-y`` variant contains only those packages that are selected with + ``PTXCONF_<PKG>=y``, while the ``-m`` variant contains only those which are + selected with ``PTXCONF_<PKG>=m`` (used for collections). + A target package rule usually adds its name to one of those variables if it + has been selected. + The union of those two sets then ends up in ``PACKAGES``. + +``EXTRA_PACKAGES``, ``EXTRA_PACKAGES-y``, ``EXTRA_PACKAGES-m`` + In analogy to ``PACKAGES``, target packages that are added to these lists will + be built normally during the build run. + In contrast however, they are not installed into a root filesystem by default + when building images, and image rules must request them explicitely. + This is useful for specialized packages that are only needed for specific + images, see :ref:`multi_image_individual_root_filesystems`. + +``HOST_PACKAGES``, ``CROSS_PACKAGES`` + Similar to ``PACKAGES``, these variables contain the host and cross packages + that are built and installed during the PTXdist build run. + There are analogous ``-y`` and ``-m`` variants of those variables too. + +Package Specific Variables +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For the following variables ``<PKG>`` is a placeholder for the package +name. It is also the Kconfig symbol name (without the ``PTXCONF_`` prefix). + +Package Definition +^^^^^^^^^^^^^^^^^^ + +``<PKG>`` + This is the name of the package including version. For most packages, + this is the name of the source archive (without suffix) and the source + directory. PTXdist will search for patches in a directory with this name. + This is usually defined as ``<name>-$(<PKG>_VERSION)``. This variable is + required for most packages. The only exception are packages that only + install some files in the targetinstall stage (e.g. from projectroot/). + +``<PKG>_VERSION`` + The version of the package. It is used as the version for the ipk + packages. As such, it is required for all packages that create such + packages. Most target packages fall in this category. + +``<PKG>_MD5`` + The md5 checksum of the source archive. PTXdist calculates the checksum + before extracting the archive and will abort if does not match. Upstream + project occasionally change the content of an archive without releasing a + new version. This check helps to ensure that all developers work with the + same source code. + +``<PKG>_SUFFIX`` + The archive suffix without the leading '.', e.g. 'tar.gz' or 'zip'. This + is only used locally to define ``<PKG>_URL`` and ``<PKG>_SOURCE``. + +``<PKG>_URL`` + This is the download URL for the source archive. It is a space separated + list of URLs. PTXdist will try each URL until it finds one that works. + There are two main reasons to provide more than one URL: 1. Additional + mirror(s) in case the main location is unavailable. 2. Some projects move + old versions into a separate directory when a new version is released. + Providing both versions of the URL ensures that PTXdist still has a + working URL after the next upstream release. + + URLs can have options. Options are appended to the URL separated by ';'. + For normal downloads the following options are supported: + + ``no-check-certificate`` to indicate that SSL certificate checking should + be disabled. + + ``no-proxy`` to disable any configured proxy. + + ``cookie:<value>`` to specify a cookie that should be sent. + + Files in the local filesystem can be addressed with ``file://`` URLs. In + this case, the URL can also point to a directory. In this case + ``<PKG>_DIR`` will be a symlink to the specified directory. 'lndir://' + can be used to create a shadow copy instead. For locations inside the BSP + the URL should use ``$(PTXDIST_WORKSPACE)`` to define the correct + absolute path. + + If no source archive is available, PTXdist can get the source from + revision control systems. 'git' and 'svn' are currently supported. Note + that this cannot be used to follow a branch! PTXdist will create the + archive defined ``<PKG>_SOURCE`` and use it if available. + + Git URLs must either start with 'git://' or end with '.git'. They have a + mandatory ``tag=<tagname>`` option. Refer :ref:`gitSources` how to make use of + it. + + Svn URLs must start with 'svn://'. They have a mandatory + ``rev=r<number>`` option. + +``<PKG>_SOURCE`` + The location of the downloaded source archive. There should be no reason + to set this to anything other than + ``$(SRCDIR)/$(<PKG>).$(<PKG>_SUFFIX)``. + + For local URLs (``file://`` or ``lndir://``) ``<PKG>_SOURCE`` must not be + set. + +``<PKG>_DIR`` + This is the directory where the source archive is extracted. In most + cases this is set to ``$(BUILDDIR)/$(<PKG>)``. However, if two packages + use the same source archive, then something else must be used to make + sure that they use different directories. See the rules for 'gdb' and + 'gdbserver' for an example. + +``<PKG>_LICENSE`` + The license of the package. The SPDX license identifiers should be used + here. Use ``proprietary`` for proprietary packages and ``ignore`` for + packages without their own license, e.g. meta packages or packages that + only install files from ``projectroot/``. + +``<PKG>_LICENSE_FILES`` + A space separated list of URLs of license text files. The URLs must be + ``file://`` URLs relative to ``<PKG>_DIR``. Absolute URLs using + ``$(PTXDIST_WORKSPACE)`` can be used in case the license text is missing + in the upstream archive. Arguments are appended with ';' as separator. + The ``md5=<md5sum>`` argument is mandatory. It defines the md5 checksum + of the full license text. ``startline=<number>;endline=<number>`` can be + used in case the specified file contains more than just the license text, + e.g. if the license is in the header of a source file. For non ASCII or + UTF-8 files the encoding can be specified with ``encoding=<enc>``. + +For most packages the variables described above are undefined by default. +However, for cross and host packages these variables default to the value +of the corresponding target package if it exists. + +``<PKG>_CONFIG`` + This variable specifies a configuration file of some kind for the + packages. For packages with ``<PKG>_CONF_TOOL`` set to ``kconfig`` the + variable must specify an absolute path to the kconfig file. For image + packages that use genimage, PTXdist will look for + ``config/images/$(<PKG>_CONFIG)`` in the BSP and PTXdist in the usual + search order. + +``<PKG>_STRIP_LEVEL`` + When PTXdist extracts source archives, it will create ``<PKG>_DIR`` + first and then extracts the archive there. If ``<PKG>_STRIP_LEVEL`` is + set to 1 (the default) then PTXdist removes the first directory level + defined inside the archive. For most packages that this is the same as + just extracting the archive. However, this is useful for packages with + badly named top-level directories or packages where the directory must be + renamed to avoid collisions (e.g. gdbserver). + + The main use-case for ``<PKG>_STRIP_LEVEL`` is to set it to 0 for + packages without a top-level directory. + + In theory ``<PKG>_STRIP_LEVEL`` could be set to 2 or more to remove more + than one directory level. + +``<PKG>_BUILD_OOT`` + If this is set to ``YES`` then PTXdist will build the package out of + tree. This is only supported for autoconf, qmake and cmake packages. The + default is ``YES`` for cmake packages and ``NO`` for everything else. + It will use ``$(<PKG>_DIR)-build`` as build directory. + + This is especially useful for ``file://`` URLS that point to directories to + keep the source tree free of build files. + +``<PKG>_SUBDIR`` + This is a directory relative to ``<PKG>_DIR``. If set, all build + operations are executed in this directory instead. By default + ``<PKG>_SUBDIR`` is undefined so all operations are executed in the + top-level directory. + +Build Environment for all Stages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``<PKG>_PATH`` + This variable defines the PATH used by all build stages. It is evaluated + as is, so it must start with ``PATH=``. If undefined, PTXdist will use + ``PATH=$(CROSS_PATH)`` for target packages ``PATH=$(HOST_PATH)`` for host + packages and ``PATH=$(HOST_CROSS_PATH)`` for cross packages. It must be + set by packages that use the variable locally in the make file or if more + directories are added, e.g. to + ``PATH=$(PTXDIST_SYSROOT_CROSS)/bin/qt5:$(CROSS_PATH)`` for packages that + use qmake from Qt5. + +``<PKG>_CFLAGS``, ``<PKG>_CPPFLAGS``, ``<PKG>_LDFLAGS`` + Compiler, preprocessor and linker are never called directly in PTXdist. + Instead, wrapper scripts are called that expand the command line before + calling the actual tool. These variables can be used to influence these + wrappers. The specified flags are added to the command line when + appropriate. In most cases this it the preferred way to add additional + flags. Adding them via environment variables or ``make`` arguments can + have unexpected side effects, such as as overwriting existing defaults. + +``<PKG>_WRAPPER_BLACKLIST`` + PTXdist has several options in the platformconfig that inject options in + the compiler command line. This is used, for example, to add hardening + options or change the debug options. This can occasionally cause problems + for packages that use the compiler in certain ways, such as the Linux + kernel or various bootloaders. With this variable a package can disable + individual options by setting it to a space separated list of the + corresponding Kconfig symbols (without the ``PTXCONF_`` prefix). + +Prepare Stage +^^^^^^^^^^^^^ + +``<PKG>_CONF_ENV`` + The environment for the prepare stage. If undefined, PTXdist will use + ``$(CROSS_ENV)`` for target packages, ``$(HOST_ENV)`` for host packages + and ``$(HOST_CROSS_ENV)`` for cross packages. It must be set by packages + that use the variable locally in the make file or if extra variables are + added. In this case the definition should start with the default value. + +``<PKG>_CONF_TOOL`` + This variable defines what tool is used to configure the package in the + prepare stage. Possible values are: + + - ``NO`` to do nothing in the prepare stage. + - ``autoconf`` for packages that use autoconf + - ``qmake`` for qmake based packages. Note: the required Qt version must + be selected. + - ``cmake`` for cmake based packages. Note ``HOST_CMAKE`` must be + selected to ensure, that cmake is available for configuration. + - ``kconfig`` for kconfig based packages. Note ``<PKG>_CONFIG`` must be + set as described above. + - ``perl`` for perl modules. + - ``python`` or ``python3`` for Python packages with a normal setup.py. + +``<PKG>_CONF_OPT`` + This variable adds arguments to the command-line of the configuration + tool. If undefined, PTXdist will use a default value that depends on the + configuration tool of the package. This default value should also be used + when adding additional options. The following defaults exist: + + - autoconf: + ``$(CROSS_AUTOCONF_USR)``/``$(HOST_AUTOCONF)``/``$(HOST_CROSS_AUTOCONF)`` + for target/host/cross packages. + - cmake: ``$(CROSS_CMAKE_USR)``/``$(HOST_CMAKE_OPT)`` for target/host + packages. Cross packages cannot be built with cmake + - qmake: ``$(CROSS_QMAKE_OPT)`` for host packages. Host and cross + packages cannot be built with qmake. + + All other configuration tools have no default options. This variable is + ignored for kconfig and python/python3. + +.. _vars_compile: + +Compile Stage +^^^^^^^^^^^^^ + +``<PKG>_MAKE_ENV`` + This variables defines additional environment variables for the compile + stage. In most cases this variable remains undefined because all + necessary defines are picked up in the prepare stage. For python/python3 + packages PTXdist will use the default value from ``<PKG>_CONF_ENV``. + For packages without configuration tool this must be set correctly, + usually based on the ``<PKG>_CONF_ENV`` default values, e,g. + ``$(CROSS_ENV)`` for target packages. + +``<PKG>_MAKE_OPT`` + This variables defines additional parameters to be forwarded to ``make`` in + order to build the package. It defaults to nothing to let ``make`` traditionally + build the first defined target. + +``<PKG>_MAKE_PAR`` + This variables informs PTXdist, if this package can be built in parallel. Some + (mostly very smart selfmade) buildsystems fail doing so. In this case this + variable can be set to ``NO``. PTXdist will then build this package with one + CPU only. The default is, to build packages in parallel. + +.. _vars_install: + +Install Stage +^^^^^^^^^^^^^ + +``<PKG>_INSTALL_OPT`` + This variable defaults to ``install`` which is used as a *target* for ``make``. + It can be overwritten if the package needs a special target to install its + results. + +.. _pkg_pkgdir: + +``<PKG>_PKGDIR`` + This variable must not be set by the user. It defines package + install directory. All files will be installed relative to this + directory. It can be used by manual install stages. It is defined as + ``$(PKGDIR)/$(<PKG>)`` which expands to + ``<platform-dir>/packages/foo-1.1.0`` on our *foo* example. + +Targetinstall Stage +^^^^^^^^^^^^^^^^^^^ + +The *targetinstall* stage has no additional variables. + +.. _image_packages: + +Image Packages +^^^^^^^^^^^^^^ + +Image packages use a different set of variables. They have the same +``<PKG>`` and ``<PKG>_DIR`` variables as other packages, but the rest is +different. + +``<PKG>_IMAGE`` + This is the filename of the image that is created by the rule. This is + usually ``$(IMAGEDIR)/<image-file-name>``. + +``<PKG>_FILES`` + This is a list of tar balls that are extracted to generate the content of + the image. PTXdist will add the necessary dependencies to these files to + recreate the image as needed. If a tar ball is created by another PTXdist + package then this package should be selected in the menu file. + +``<PKG>_PKGS`` + This is another mechanism to add files to the image. It can be uses + instead of or in addition to ``<PKG>_FILES``. It must be set to a list of + ptxdist packages (the lowercase name of the packages). PTXdist will add + the necessary dependencies. + + Note that this will not ensure that the packages are enabled or that all + all package dependencies are satisfied. ``$(PTX_PACKAGES_INSTALL)`` can + be used to specify all enabled packages. Or ``$(call ptx/collection, + $(PTXDIST_WORKSPACE)/configs/<collection-file-name>)`` can be uses to to + specify the packages enabled by this collection. In both cases ``=`` must + be uses instead of ``:=`` due to the makefile include order. + +``<PKG>_CONFIG`` + ``genimage`` packages use this to specify the ``genimage`` configuration + file. PTXdist will search for the specified file name in + ``config/images/`` in the BSP, platform and PTXdist in the usual search + order. + +``<PKG>_NFSROOT`` + If this is set to ``YES`` then PTXdist will create a special nfsroot + directory that contains only the files from the packages specified in + ``<PKG>_PKGS``. This is useful if the normal nfsroot directory contains + conflicting files from multiple images. The created nfsroot directory is + ``<platform-dir>/nfsroot/<image-name>``. + +``<PKG>_LABEL`` + This is a tar label to put on an image. This is supported by + ``image-root-tgz`` and images created with the ``image-tgz`` template. diff --git a/doc/ref_manual.rst b/doc/ref_manual.rst index 4444e0192235..6541da3eaa00 100644 --- a/doc/ref_manual.rst +++ b/doc/ref_manual.rst @@ -1,1545 +1,9 @@ PTXdist Reference ================= -Variables Reference -------------------- - -The following variables are provided by PTXdist to simplify creating -rule files. Every developer should use these variables in every single -line in the **rule file** to avoid any further adaption when external paths -are changed. - -To get their content related to the current project, we can simply run -a: - -:: - - $ ptxdist print PTXDIST_TOPDIR - /usr/local/lib/ptxdist-|ptxdistVendorVersion| - -Replace the ``PTXDIST_TOPDIR`` with one of the other generic variables -PTXdist provides. - -Global Variables -~~~~~~~~~~~~~~~~ - -``PTXDIST_TOPDIR`` - Points always to the installation directory of PTXdist. - -.. _ptxdist_workspace: - -``PTXDIST_WORKSPACE`` - Everything that references ``PTXDIST_WORKSPACE`` will use the active - projects’s folder. - -``PTXDIST_SYSROOT_CROSS`` - ``PTXDIST_SYSROOT_CROSS`` points to a directory tree all cross relevant - executables, libraries and header files are installed to in the current - project. All of the project’s packages built for the host to create data - for the target are searching in this directory tree for their - dependencies (executables, header and library files). Use - ``$(PTXDIST_SYSROOT_CROSS)/bin`` to install executables, - ``$(PTXDIST_SYSROOT_CROSS)/include`` for header files and - ``$(PTXDIST_SYSROOT_CROSS)/lib`` for libraries. - -``PTXDIST_SYSROOT_HOST`` - ``PTXDIST_SYSROOT_HOST`` points to a directory tree all host relevant - executables, libraries and header files are installed to. All project’s - packages built for the host are searching in this directory tree for - their dependencies (executables, header and library files). Use - ``$(PTXDIST_SYSROOT_HOST)/bin`` to install executables, - ``$(PTXDIST_SYSROOT_HOST)/include`` for header files and - ``$(PTXDIST_SYSROOT_HOST)/lib`` for libraries. - -``PTXDIST_SYSROOT_TARGET`` - ``PTXDIST_SYSROOT_TARGET`` points to a directory tree all target - relevant libraries and header files are installed to. All project’s - packages built for the target are searching in this directory tree for - their dependencies (header and library files). These files are for - compile time only (for example to link a target executable against a - target library), not for run-time! Use - ``$(PTXDIST_SYSROOT_TARGET)/include`` for header files and - ``$(PTXDIST_SYSROOT_TARGET)/lib`` for libraries. - -Other useful variables: - -``CROSS_PATH`` - Use to find cross tools. This path must be used to create anything that - depends on the target’s architecture, but needs something running on the - host to do the job. Examples: - - **Creating a UBI image from the target’s root filesystem** - This will need a tool running on the host, but it will create data - or code that runs on or is used on the target - - **Building a library for the target** - If this library needs other resources to be built (other libraries) - its ``configure`` finds the right information in this path. - -``HOST_PATH`` - Used to find host tools. This path must be used to create anything that - doesn't depend on the architecture. - -``ROOTDIR`` - ``ROOTDIR`` points to the root of the target’s root filesystem in the - current project. Used in very rare cases (to create strange packages - based on data in target’s root filesystem for example). - -``PTXCONF_PLATFORM`` - ``PTXCONF_PLATFORM`` expands to the name of the currently selected - platform. This name is used in various file names and paths. - -``PTXDIST_PLATFORMSUFFIX`` - ``PTXDIST_PLATFORMSUFFIX`` expands to the name of the currently selected - platform, but with a leading dot. This is used in various files PTXdist - should search for. - -.. _ptxdist_platformconfigdir: - -``PTXDIST_PLATFORMCONFIGDIR`` - ``PTXDIST_PLATFORMCONFIGDIR`` points to the directory tree of the - currently selected platform. This path is used in various search - functions. - -``PTXDIST_PLATFORMDIR`` - ``PTXDIST_PLATFORMDIR`` points to the directory build tree of the - currently selected platform. - -``PACKAGES``, ``PACKAGES-y``, ``PACKAGES-m`` - ``PACKAGES`` is a list of space-separated lowercase package names that are - built and installed during the PTXdist build run, and installed into the - target root filesystem when building images. - - The ``-y`` variant contains only those packages that are selected with - ``PTXCONF_<PKG>=y``, while the ``-m`` variant contains only those which are - selected with ``PTXCONF_<PKG>=m`` (used for collections). - A target package rule usually adds its name to one of those variables if it - has been selected. - The union of those two sets then ends up in ``PACKAGES``. - -``EXTRA_PACKAGES``, ``EXTRA_PACKAGES-y``, ``EXTRA_PACKAGES-m`` - In analogy to ``PACKAGES``, target packages that are added to these lists will - be built normally during the build run. - In contrast however, they are not installed into a root filesystem by default - when building images, and image rules must request them explicitely. - This is useful for specialized packages that are only needed for specific - images, see :ref:`multi_image_individual_root_filesystems`. - -``HOST_PACKAGES``, ``CROSS_PACKAGES`` - Similar to ``PACKAGES``, these variables contain the host and cross packages - that are built and installed during the PTXdist build run. - There are analogous ``-y`` and ``-m`` variants of those variables too. - -Package Specific Variables -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For the following variables ``<PKG>`` is a placeholder for the package -name. It is also the Kconfig symbol name (without the ``PTXCONF_`` prefix). - -Package Definition -^^^^^^^^^^^^^^^^^^ - -``<PKG>`` - This is the name of the package including version. For most packages, - this is the name of the source archive (without suffix) and the source - directory. PTXdist will search for patches in a directory with this name. - This is usually defined as ``<name>-$(<PKG>_VERSION)``. This variable is - required for most packages. The only exception are packages that only - install some files in the targetinstall stage (e.g. from projectroot/). - -``<PKG>_VERSION`` - The version of the package. It is used as the version for the ipk - packages. As such, it is required for all packages that create such - packages. Most target packages fall in this category. - -``<PKG>_MD5`` - The md5 checksum of the source archive. PTXdist calculates the checksum - before extracting the archive and will abort if does not match. Upstream - project occasionally change the content of an archive without releasing a - new version. This check helps to ensure that all developers work with the - same source code. - -``<PKG>_SUFFIX`` - The archive suffix without the leading '.', e.g. 'tar.gz' or 'zip'. This - is only used locally to define ``<PKG>_URL`` and ``<PKG>_SOURCE``. - -``<PKG>_URL`` - This is the download URL for the source archive. It is a space separated - list of URLs. PTXdist will try each URL until it finds one that works. - There are two main reasons to provide more than one URL: 1. Additional - mirror(s) in case the main location is unavailable. 2. Some projects move - old versions into a separate directory when a new version is released. - Providing both versions of the URL ensures that PTXdist still has a - working URL after the next upstream release. - - URLs can have options. Options are appended to the URL separated by ';'. - For normal downloads the following options are supported: - - ``no-check-certificate`` to indicate that SSL certificate checking should - be disabled. - - ``no-proxy`` to disable any configured proxy. - - ``cookie:<value>`` to specify a cookie that should be sent. - - Files in the local filesystem can be addressed with ``file://`` URLs. In - this case, the URL can also point to a directory. In this case - ``<PKG>_DIR`` will be a symlink to the specified directory. 'lndir://' - can be used to create a shadow copy instead. For locations inside the BSP - the URL should use ``$(PTXDIST_WORKSPACE)`` to define the correct - absolute path. - - If no source archive is available, PTXdist can get the source from - revision control systems. 'git' and 'svn' are currently supported. Note - that this cannot be used to follow a branch! PTXdist will create the - archive defined ``<PKG>_SOURCE`` and use it if available. - - Git URLs must either start with 'git://' or end with '.git'. They have a - mandatory ``tag=<tagname>`` option. Refer :ref:`gitSources` how to make use of - it. - - Svn URLs must start with 'svn://'. They have a mandatory - ``rev=r<number>`` option. - -``<PKG>_SOURCE`` - The location of the downloaded source archive. There should be no reason - to set this to anything other than - ``$(SRCDIR)/$(<PKG>).$(<PKG>_SUFFIX)``. - - For local URLs (``file://`` or ``lndir://``) ``<PKG>_SOURCE`` must not be - set. - -``<PKG>_DIR`` - This is the directory where the source archive is extracted. In most - cases this is set to ``$(BUILDDIR)/$(<PKG>)``. However, if two packages - use the same source archive, then something else must be used to make - sure that they use different directories. See the rules for 'gdb' and - 'gdbserver' for an example. - -``<PKG>_LICENSE`` - The license of the package. The SPDX license identifiers should be used - here. Use ``proprietary`` for proprietary packages and ``ignore`` for - packages without their own license, e.g. meta packages or packages that - only install files from ``projectroot/``. - -``<PKG>_LICENSE_FILES`` - A space separated list of URLs of license text files. The URLs must be - ``file://`` URLs relative to ``<PKG>_DIR``. Absolute URLs using - ``$(PTXDIST_WORKSPACE)`` can be used in case the license text is missing - in the upstream archive. Arguments are appended with ';' as separator. - The ``md5=<md5sum>`` argument is mandatory. It defines the md5 checksum - of the full license text. ``startline=<number>;endline=<number>`` can be - used in case the specified file contains more than just the license text, - e.g. if the license is in the header of a source file. For non ASCII or - UTF-8 files the encoding can be specified with ``encoding=<enc>``. - -For most packages the variables described above are undefined by default. -However, for cross and host packages these variables default to the value -of the corresponding target package if it exists. - -``<PKG>_CONFIG`` - This variable specifies a configuration file of some kind for the - packages. For packages with ``<PKG>_CONF_TOOL`` set to ``kconfig`` the - variable must specify an absolute path to the kconfig file. For image - packages that use genimage, PTXdist will look for - ``config/images/$(<PKG>_CONFIG)`` in the BSP and PTXdist in the usual - search order. - -``<PKG>_STRIP_LEVEL`` - When PTXdist extracts source archives, it will create ``<PKG>_DIR`` - first and then extracts the archive there. If ``<PKG>_STRIP_LEVEL`` is - set to 1 (the default) then PTXdist removes the first directory level - defined inside the archive. For most packages that this is the same as - just extracting the archive. However, this is useful for packages with - badly named top-level directories or packages where the directory must be - renamed to avoid collisions (e.g. gdbserver). - - The main use-case for ``<PKG>_STRIP_LEVEL`` is to set it to 0 for - packages without a top-level directory. - - In theory ``<PKG>_STRIP_LEVEL`` could be set to 2 or more to remove more - than one directory level. - -``<PKG>_BUILD_OOT`` - If this is set to ``YES`` then PTXdist will build the package out of - tree. This is only supported for autoconf, qmake and cmake packages. The - default is ``YES`` for cmake packages and ``NO`` for everything else. - It will use ``$(<PKG>_DIR)-build`` as build directory. - - This is especially useful for ``file://`` URLS that point to directories to - keep the source tree free of build files. - -``<PKG>_SUBDIR`` - This is a directory relative to ``<PKG>_DIR``. If set, all build - operations are executed in this directory instead. By default - ``<PKG>_SUBDIR`` is undefined so all operations are executed in the - top-level directory. - -Build Environment for all Stages -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``<PKG>_PATH`` - This variable defines the PATH used by all build stages. It is evaluated - as is, so it must start with ``PATH=``. If undefined, PTXdist will use - ``PATH=$(CROSS_PATH)`` for target packages ``PATH=$(HOST_PATH)`` for host - packages and ``PATH=$(HOST_CROSS_PATH)`` for cross packages. It must be - set by packages that use the variable locally in the make file or if more - directories are added, e.g. to - ``PATH=$(PTXDIST_SYSROOT_CROSS)/bin/qt5:$(CROSS_PATH)`` for packages that - use qmake from Qt5. - -``<PKG>_CFLAGS``, ``<PKG>_CPPFLAGS``, ``<PKG>_LDFLAGS`` - Compiler, preprocessor and linker are never called directly in PTXdist. - Instead, wrapper scripts are called that expand the command line before - calling the actual tool. These variables can be used to influence these - wrappers. The specified flags are added to the command line when - appropriate. In most cases this it the preferred way to add additional - flags. Adding them via environment variables or ``make`` arguments can - have unexpected side effects, such as as overwriting existing defaults. - -``<PKG>_WRAPPER_BLACKLIST`` - PTXdist has several options in the platformconfig that inject options in - the compiler command line. This is used, for example, to add hardening - options or change the debug options. This can occasionally cause problems - for packages that use the compiler in certain ways, such as the Linux - kernel or various bootloaders. With this variable a package can disable - individual options by setting it to a space separated list of the - corresponding Kconfig symbols (without the ``PTXCONF_`` prefix). - -Prepare Stage -^^^^^^^^^^^^^ - -``<PKG>_CONF_ENV`` - The environment for the prepare stage. If undefined, PTXdist will use - ``$(CROSS_ENV)`` for target packages, ``$(HOST_ENV)`` for host packages - and ``$(HOST_CROSS_ENV)`` for cross packages. It must be set by packages - that use the variable locally in the make file or if extra variables are - added. In this case the definition should start with the default value. - -``<PKG>_CONF_TOOL`` - This variable defines what tool is used to configure the package in the - prepare stage. Possible values are: - - - ``NO`` to do nothing in the prepare stage. - - ``autoconf`` for packages that use autoconf - - ``qmake`` for qmake based packages. Note: the required Qt version must - be selected. - - ``cmake`` for cmake based packages. Note ``HOST_CMAKE`` must be - selected to ensure, that cmake is available for configuration. - - ``kconfig`` for kconfig based packages. Note ``<PKG>_CONFIG`` must be - set as described above. - - ``perl`` for perl modules. - - ``python`` or ``python3`` for Python packages with a normal setup.py. - -``<PKG>_CONF_OPT`` - This variable adds arguments to the command-line of the configuration - tool. If undefined, PTXdist will use a default value that depends on the - configuration tool of the package. This default value should also be used - when adding additional options. The following defaults exist: - - - autoconf: - ``$(CROSS_AUTOCONF_USR)``/``$(HOST_AUTOCONF)``/``$(HOST_CROSS_AUTOCONF)`` - for target/host/cross packages. - - cmake: ``$(CROSS_CMAKE_USR)``/``$(HOST_CMAKE_OPT)`` for target/host - packages. Cross packages cannot be built with cmake - - qmake: ``$(CROSS_QMAKE_OPT)`` for host packages. Host and cross - packages cannot be built with qmake. - - All other configuration tools have no default options. This variable is - ignored for kconfig and python/python3. - -.. _vars_compile: - -Compile Stage -^^^^^^^^^^^^^ - -``<PKG>_MAKE_ENV`` - This variables defines additional environment variables for the compile - stage. In most cases this variable remains undefined because all - necessary defines are picked up in the prepare stage. For python/python3 - packages PTXdist will use the default value from ``<PKG>_CONF_ENV``. - For packages without configuration tool this must be set correctly, - usually based on the ``<PKG>_CONF_ENV`` default values, e,g. - ``$(CROSS_ENV)`` for target packages. - -``<PKG>_MAKE_OPT`` - This variables defines additional parameters to be forwarded to ``make`` in - order to build the package. It defaults to nothing to let ``make`` traditionally - build the first defined target. - -``<PKG>_MAKE_PAR`` - This variables informs PTXdist, if this package can be built in parallel. Some - (mostly very smart selfmade) buildsystems fail doing so. In this case this - variable can be set to ``NO``. PTXdist will then build this package with one - CPU only. The default is, to build packages in parallel. - -.. _vars_install: - -Install Stage -^^^^^^^^^^^^^ - -``<PKG>_INSTALL_OPT`` - This variable defaults to ``install`` which is used as a *target* for ``make``. - It can be overwritten if the package needs a special target to install its - results. - -.. _pkg_pkgdir: - -``<PKG>_PKGDIR`` - This variable must not be set by the user. It defines package - install directory. All files will be installed relative to this - directory. It can be used by manual install stages. It is defined as - ``$(PKGDIR)/$(<PKG>)`` which expands to - ``<platform-dir>/packages/foo-1.1.0`` on our *foo* example. - -Targetinstall Stage -^^^^^^^^^^^^^^^^^^^ - -The *targetinstall* stage has no additional variables. - -.. _image_packages: - -Image Packages -^^^^^^^^^^^^^^ - -Image packages use a different set of variables. They have the same -``<PKG>`` and ``<PKG>_DIR`` variables as other packages, but the rest is -different. - -``<PKG>_IMAGE`` - This is the filename of the image that is created by the rule. This is - usually ``$(IMAGEDIR)/<image-file-name>``. - -``<PKG>_FILES`` - This is a list of tar balls that are extracted to generate the content of - the image. PTXdist will add the necessary dependencies to these files to - recreate the image as needed. If a tar ball is created by another PTXdist - package then this package should be selected in the menu file. - -``<PKG>_PKGS`` - This is another mechanism to add files to the image. It can be uses - instead of or in addition to ``<PKG>_FILES``. It must be set to a list of - ptxdist packages (the lowercase name of the packages). PTXdist will add - the necessary dependencies. - - Note that this will not ensure that the packages are enabled or that all - all package dependencies are satisfied. ``$(PTX_PACKAGES_INSTALL)`` can - be used to specify all enabled packages. Or ``$(call ptx/collection, - $(PTXDIST_WORKSPACE)/configs/<collection-file-name>)`` can be uses to to - specify the packages enabled by this collection. In both cases ``=`` must - be uses instead of ``:=`` due to the makefile include order. - -``<PKG>_CONFIG`` - ``genimage`` packages use this to specify the ``genimage`` configuration - file. PTXdist will search for the specified file name in - ``config/images/`` in the BSP, platform and PTXdist in the usual search - order. - -``<PKG>_NFSROOT`` - If this is set to ``YES`` then PTXdist will create a special nfsroot - directory that contains only the files from the packages specified in - ``<PKG>_PKGS``. This is useful if the normal nfsroot directory contains - conflicting files from multiple images. The created nfsroot directory is - ``<platform-dir>/nfsroot/<image-name>``. - -``<PKG>_LABEL`` - This is a tar label to put on an image. This is supported by - ``image-root-tgz`` and images created with the ``image-tgz`` template. - -.. _reference_macros: - -Rule File Macro Reference -------------------------- - -Rules files in PTXdist are using macros to get things work. Its highly -recommended to use these macros instead of doing something by ourself. Using these -macros is portable and such easier to maintain in the case a project should be -upgraded to a more recent PTXdist version. - -This chapter describes the predefined macros in PTXdist and their usage. - -Whenever one of these macros installs something to the target's root filesystem, -it also accepts user and group IDs which are common in all filesystems Linux -supports. These IDs can be given as numerical values and as text strings. -In the case text strings are given PTXdist converts them into the -corresponding numerical value based on the BSP local files :file:`passwd` and :file:`group`. -If more than one file with these names are present in the BSP PTXdist follows -its regular rules which one it prefers. - -Many paths shown here contains some parts in angle brackets. These have -special meanings in this document. - -**<platform>** - The name of a platform. Corresponds to the variable - ``PTXCONF_PLATFORM`` -**<platform-src>** - The directory where the platform is defined. Corresponds to the variable - ``PTXDIST_PLATFORMCONFIGDIR`` -**<platform-dir>** - Concatenated directory name with a leading *platform-* and the name of the - selected platform name, e.g. <platform>. If the name of the currently active - platform is *foo*, the final directory name is *platform-foo*. - Corresponds to the variable ``PTXDIST_PLATFORMDIR`` - -.. note:: The list of supported macros is not complete yet. - -targetinfo -~~~~~~~~~~ - -Usage: - -.. code-block:: make - - $(call targetinfo) - -Gives a feedback, what build *stage* is just started. That's why it -should always be the first call for each *stage*. For the package -*foo* and the *compile stage* it will output: - -.. code-block:: bash - - -------------------- - target: foo.compile - -------------------- - -touch -~~~~~~ - -Usage: - -.. code-block:: make - - $(call touch) - -Gives a feedback, what build *stage* is just finished. That's why it -should always be the last call for each *stage*. For the package -*foo* and the *compile stage* it will output: - -.. code-block:: bash - - finished target foo.compile - -clean -~~~~~ - -Usage: - -.. code-block:: make - - $(call clean, <directory path>) - -Removes the given directory ``<directory path>`` - -.. _install_copy: - -world/get, world/extract, world/prepare, world/compile, world/install -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Usage: - -.. code-block:: make - - $(call world/get, <PKG>) - -The same for all other macros. These are the default build commands for the -corresponding stages. For more details see the documentation of the default -stages below. - -compile -~~~~~~~ - -Usage: - -.. code-block:: make - - $(call compile, <PKG>, <build arguments>) - -This macro is very similar to ``world/compile``. The only differences is -that is uses the specified ``build arguments`` instead of -``<PKG>_MAKE_OPT``. This is usefull if ``make`` needs to be called more -than once in the compile stage. - -world/execute, execute -~~~~~~~~~~~~~~~~~~~~~~ - -Usage: - -.. code-block:: make - - $(call execute, <PKG>, <command with arguments>) - $(call world/execute, <PKG>, <command with arguments>) - -These macros make it possible to execute arbitrary commands during the -build stages. This is usefull because the environment is identical to the -default build commands ``world/*``. - -``world/execute`` also handles the generic setup handled in the current -build stage. For ``prepare`` this means that, for out ot tree builds, the -build directory is deleted prior to executing the specified command. -For ``install`` the package directory is deleted. - -When ``--verbose`` is used then the full command is logged. With -``--quiet`` both stdout and stderr are redirected to the logfile. - -install_copy -~~~~~~~~~~~~~ - -Usage: - -.. code-block:: make - - $(call install_copy, <package>, <UID>, <GID>, <permission>, <source> [, <dest> [, <strip> ]]) - -Installs given file or directory into: - -* the project's ``<platform-dir>/root/`` -* an ipkg/opkg packet in the project's ``<platform-dir>/packages/`` - -Some of the parameters have fixed meanings: - -**<package>** - Name of the IPKG/OPKG the macro should work on -**<UID>** - User ID the file should use in the target's root filesystem -**<GID>** - Group ID the file should use in the target's root filesystem -**<permission>** - Permission (in an octal value) the file should use in the target's root filesystem - -The remaining parameters vary with the use case: - -The ``<source>`` parameter can be: - -* a directory path that should be created in the target's root filesystem. - In this case the <destination> must be omitted. - The given path must always start with a ``/`` and means the root - of the target's filesystem. -* an absolute path to a file that should be copied to the target's root - filesystem. To avoid fixed paths, all packages are providing the - <PKG>_DIR variable. So, this parameter in our - *foo* example package can be a ``$(FOO_DIR)/foo``. -* a minus sign (``-``). PTXdist uses the <destination> - parameter in this case to locate the file to copy from. - The <destination> is uses a path relative to the :ref:`package install - directory<pkg_pkgdir>`. This only works if the package uses the default - or a similar *install* stage. For our *foo* example used source file is - ``<platform-dir>/packages/foo-1.1.0/<destination>``. - -The ``<dest>`` parameter can be: - -* omitted if a directory in target's root filesystem should be created. - For this case the directory to be created is in the <source> parameter. -* an absolute path and filename with its root in target's root filesystem. - It must start with a slash (``//``). If also the <source> - parameter was given, the file can be renamed while copying. - If the <source> parameter was given as a minus - sign (``-``) the <destination> is also used to - locate the source. For our *foo* example package if we give - <destination> as ``/usr/bin/foo``, PTXdist - copies the file ``<platform-dir>/packages/foo-1.1.0/usr/bin/foo`` - -The ``<strip>`` is a complete optional parameter to prevent -this macro from the regular stripping process it does on files. Most of the cases -stripping debug information from files is intended. But some kind of files getting -destroyed when this stripping happens to them. One example is a Linux kernel module. -If it gets stripped, it can't be loaded into the kernel anymore. - -**full strip** - fully strip the file while installing when this parameter is **y** or not - given at all (default case). -**partially strip** - only strips real debug information from the file when this parameter is - **k**. Useful to keep Linux kernel module loadable at run-time -**no strip** - preserve the file from being stripped when this parameter is one of the - following: **0**, **n**, **no**, **N** or **NO**. - -Due to the complexity of this macro, here are some usage examples: - -Create a directory in the root filesystem: - -.. code-block:: make - - $(call install_copy, foo, 0, 0, 0755, /home/user-foo) - -Copy a file from the package build directory to the root filesystem: - -.. code-block:: make - - $(call install_copy, foo, 0, 0, 0755, $(FOO_DIR)/foo, /usr/bin/foo) - -Copy a file from the package build directory to the root filesystem and rename -it: - -.. code-block:: make - - $(call install_copy, foo, 0, 0, 0755, $(FOO_DIR)/foo, /usr/bin/bar) - -Copy a file from the package install directory to the root filesystem: - -.. code-block:: make - - $(call install_copy, foo, 0, 0, 0755, -, /usr/bin/foo) - -.. _install_tree,reference: - -install_tree -~~~~~~~~~~~~ - -Usage: - -.. code-block:: make - - $(call install_tree, <package>, <UID>, <GID>, <source dir>, <destination dir>) - -Installs the whole directory tree with all files from the given directory into: - -* the project's ``<platform-dir>/root/`` -* an ipkg packet in the project's ``<platform-dir>/packages/`` - -Some of the parameters have fixed meanings: - -**<package>** - Name of the IPKG/OPKG the macro should work on -**<UID>** - User ID the directories and files should use in the target's root filesystem - or ``-`` to keep the UID from the source tree -**<GID>** - Group ID the directories and files should use in the target's root filesystem - or ``-`` to keep the GID from the source tree -**<source dir>** - This is the path to the tree of directories and files to be installed. It can - be ``-`` to use the package directory of the current package instead -**<destination dir>** - The basename of the to-be-installed tree in the root filesystem - -Note: This installation macro - -* uses the same permission flags in the destination dir as found - in the source dir. This is valid for directories and regular files -* skips all directories with names like ``.svn``, ``.git``, ``.pc`` and - ``CVS`` in the source directory - -Examples: - -Install the whole tree found in ``/home/jbe/foo`` to the root filesystem -at location ``/usr/share/bar``. - -.. code-block:: make - - $(call install_tree, foo, 0, 0, /home/jbe/foo, /usr/share/bar) - -Install all files from the tree found in the current package FOO to the root -filesystem at location ``/usr/share/bar``. - -.. code-block:: make - - $(call install_tree, foo, 0, 0, -, /usr/share/bar) - -If the current package is ``foo-1.0`` the base path for the directory tree -will be ``$(PKGDIR)/foo-1.0/usr/share/bar``. - -install_alternative_tree -~~~~~~~~~~~~~~~~~~~~~~~~ - -Usage: - -.. code-block:: make - - $(call install_alternative_tree, <package>, <UID>, <GID>, <destination dir>) - -Installs the whole source directory tree with all files from the given directory into: - -* the project's ``<platform-dir>/root/`` -* an ipkg packet in the project's ``<platform-dir>/packages/`` - -The ``<destination dir>`` is used like in the ``install_alternative`` to let -PTXdist search in the same directories and order for the given directory. - -Some of the parameters have fixed meanings: - -**<package>** - Name of the IPKG/OPKG the macro should work on -**<UID>** - User ID the directories and files should use in the target's root filesystem - or ``-`` to keep the UID from the source -**<GID>** - Group ID the directories and files should use in the target's root - filesystem or ``-`` to keep the GID from the source -**<destination dir>** - The basename of the to-be-installed tree in the root filesystem - -.. note:: This installation macro - - * uses the same permission flags in the destination dir as found in the source - dir. This is valid for directories and regular files - * skips all directories with names like ``.svn``, ``.git``, ``.pc`` and ``CVS`` - in the source directory - -Examples: - -Install the whole tree found in project's ``projectroot/usr/share/bar`` -to the root filesystem at location ``/usr/share/bar``. - -.. code-block:: make - - $(call install_alternative_tree, foo, 0, 0, /usr/share/bar) - -To install nothing, use a symlink to ``/dev/null`` instead of the base -directory. See :ref:`install_alternative` for more details. - -.. _install_alternative: - -install_alternative -~~~~~~~~~~~~~~~~~~~ - -Usage: - -.. code-block:: make - - $(call install_alternative, <package>, <UID>, <GID>, <permission>, <destination>) - -Installs given files or directories into: - -* the project's ``<platform-dir>/root/`` -* an ipkg/opkg packet in the project's ``<platform-dir>/packages/`` - -The base parameters and their meanings: - -**<package>** - Name of the IPKG/OPKG the macro should work on -**<UID>** - User ID the file should use in the target's root filesystem -**<GID>** - Group ID the file should use in the target's root filesystem -**<permission>** - Permission (in an octal value) the file should use in the target's root filesystem - -The parameter <destination> is meant as an absolute path -and filename in target's root filesystem. PTXdist searches for the source -of this file in: - -* the local project -* in the used platform -* PTXdist's install path -* in the current package - -As this search algorithm is complex, here an example for the file -``/etc/foo`` in package ``FOO``. PTXdist will search for this -file in the following order: - -* project's directory ``projectroot.<platform>/etc/foo`` -* project's directory ``projectroot/etc/foo.<platform>`` -* platform's directory ``<platform-src>/projectroot/etc/foo.<platform>`` -* project's directory ``projectroot/etc/foo`` -* platform's directory ``<platform-src>/projectroot/etc/foo`` -* ptxdist's directory ``projectroot/etc/foo`` -* package's directory ``$(FOO_PKGDIR)/etc/foo`` -* package's directory ``$(FOO_DIR)/etc/foo`` - -The generic rules are looking like the following: - -* ``$(PTXDIST_WORKSPACE)/projectroot$(PTXDIST_PLATFORMSUFFIX)/etc/foo`` -* ``$(PTXDIST_WORKSPACE)/projectroot/etc/foo$(PTXDIST_PLATFORMSUFFIX)`` -* ``$(PTXDIST_PLATFORMCONFIGDIR)/projectroot/etc/foo$(PTXDIST_PLATFORMSUFFIX)`` -* ``$(PTXDIST_WORKSPACE)/projectroot/etc/foo`` -* ``$(PTXDIST_PLATFORMCONFIGDIR)/projectroot/etc/foo`` -* ``$(PTXDIST_TOPDIR)/projectroot/etc/foo`` -* ``$(FOO_PKGDIR)/etc/foo`` -* ``$(FOO_DIR)/etc/foo`` - -Note: You can get the current values for the listed variables above via running -PTXdist with the ``print`` parameter: - -.. code-block:: bash - - $ ptxdist print PTXDIST_PLATFORMSUFFIX - -``install_alternative`` is used by upstream PTXdist packages to install -config files. In some rare use-cases the file should not be installed at -all. For example if the config file is generated at runtime or provided by -a special configuration package. This is possible by creating a symlink to -``/dev/null`` instead of a file at one of the locations described above. -PTXdist skips installing the file if it detects such a symlink. - -install_link -~~~~~~~~~~~~ - -Usage: - -.. code-block:: make - - $(call install_link, <package>, <point to>, <where>) - -Installs a symbolic link into: - -* the project's ``<platform-dir>/root/`` -* an ipkg/opkg packet in the project's ``<platform-dir>/packages/`` - -The parameters and their meanings: - -**<package>** - Name of the IPKG/OPKG the macro should work on -**<point to>** - Path and name the link should point to. Note: This macro rejects absolute - paths. If needed use relative paths instead. -**<where>** - Path and name of the symbolic link. - -A few usage examples. - -Create a symbolic link as ``/usr/lib/libfoo.so`` pointing to -``libfoo.so.1.1.0`` in the same directory: - -.. code-block:: make - - $(call install_link, foo, libfoo.so.1.1.0, /usr/lib/libfoo.so) - -Create a symbolic link as ``/usr/bin/foo`` pointing to ``/bin/bar``: - -.. code-block:: make - - $(call install_link, foo, ../../bin/bar, /usr/bin/foo) - -.. _install_archive: - -install_archive -~~~~~~~~~~~~~~~ - -Usage: - -.. code-block:: make - - $(call install_archive, <package>, <UID>, <GID>, <archive> , <base path>) - -Installs archives content into: - -* the project's ``<platform-dir>/root/`` -* an ipkg/opkg packet in the project's ``<platform-dir>/packages/`` - -All parameters have fixed meanings: - -**<package>** - Name of the IPKG/OPKG the macro should work on -**<UID>** - User ID all files and directory of the archive should use in the target's - root filesystem. A ``-`` uses the file's/directory's UID in the archive -**<GID>** - Group ID the files and directories should use in the target's root filesystem. - A ``-`` uses the file's/directory's GID in the archive -**<archive>** - Name of the archive to be used in this call. The given path and filename is - used as is -**<base path>** - Base path component in the root filesystem the archive should be extracted - to. Can be just ``/`` for root. - -install_glob -~~~~~~~~~~~~ - -Usage: - -.. code-block:: make - - $(call install_glob, <package>, <UID>, <GID>, <source dir>, <destination dir>, <yglob>, <nglob>[, <strip>]) - -Installs parts of a directory tree with all files from the given directory -into: - -* the project's ``<platform-dir>/root/`` -* an ipkg packet in the project's ``<platform-dir>/packages/`` - -Some of the parameters have fixed meanings: - -**<package>** - Name of the IPKG/OPKG the macro should work on -**<UID>** - User ID the directories and files should use in the target's root filesystem - or ``-`` to keep the UID from the source tree -**<GID>** - Group ID the directories and files should use in the target's root filesystem - or ``-`` to keep the GID from the source tree -**<source dir>** - This is the path to the tree of directories and files to be installed. It can - be ``-`` to use the package directory of the current package instead -**<destination dir>** - The basename of the to-be-installed tree in the root filesystem -**<yglob>** - A list of pathname patterns. All files or directories that match _any_ - pattern in the list are installed. Note: the patterns must match the - whole absolute path, e.g. ``*/foo``. An empty list is equivalent to a - pattern that matches all files. -**<nglob>** - Like ``<yglob>`` but any matching files or directories will not be - installed. For directories, this includes the whole contents of the - directory. - -Except for the pathname patterns, this command works like ``install_tree``. -The ``<yglob>`` and ``<nglob>`` patterns are combined: Only files that -match ``<yglob>`` and do not match ``<nglob>`` are installed. - -Examples: - -Install all shared libraries found in ``$(FOO_PKGDIR)/usr/lib/foo`` except -libbar.so - -.. code-block:: make - - $(call install_glob, foo, 0, 0, -, /usr/lib/foo, *.so, */libbar.so) - -install_lib -~~~~~~~~~~~ - -Usage: - -.. code-block:: make - - $(call install_lib, <package>, <UID>, <GID>, <permission>, <libname>) - -Installs the shared library <libname> into the root filesystem. - -* the project's ``<platform-dir>/root/`` -* an ipkg/opkg packet in the project's ``<platform-dir>/packages/`` - -The parameters and their meanings: - -**<package>** - Name of the IPKG/OPKG the macro should work on -**<UID>** - User ID the file should use in the target's root filesystem -**<GID>** - Group ID the directories and files should use in the target's root filesystem -**<permission>** - Permission (as an octal value) the library should use in the target's root - filesystem (mostly 0644) -**<libname>** - Basename of the library without any extension and path - -The ``install_lib`` macro searches for the library at the most -common directories ``/lib`` and ``/usr/lib``. And it searches always -in the package's corresponding directory in ``<platform-dir>/packages/``. -It also handles all required links to make the library work at run-time. - -An example. - -Lets assume the package 'foo-1.0.0' has installed the library ``libfoo`` into -its ``<platform-dir>/packages/foo-1.0.0`` at: - -* the lib: ``<platform-dir>/packages/foo-1.0.0/usr/lib/libfoo1.so.0.0.0`` -* first link: ``<platform-dir>/packages/foo-1.0.0/usr/lib/libfoo1.so.0`` -* second link: ``<platform-dir>/packages/foo-1.0.0/usr/lib/libfoo1.so`` - -.. note:: The second link is only needed for the linker at build-time to - resolve ``-lfoo1``. It is not needed at run-time so ``install_lib`` will - skip it. - -To install this library and its corresponding link, the following line does the job: - -.. code-block:: make - - $(call install_lib, foo, 0, 0, 0644, libfoo1) - -Note: The package's install stage must be 'DESTDIR' aware to be able to make -it install its content into the corresponding packages directory (in our example -``<platform-dir>/packages/foo-1.0.0/`` here). - -install_replace -~~~~~~~~~~~~~~~ - -Usage: - -.. code-block:: make - - $(call install_replace, <package>, <filename>, <placeholder>, <value>) - -Replace placeholder with value in a previously installed file. - -The parameters and their meanings: - -**<package>** - Name of the IPKG/OPKG the macro should work on -**<filename>** - Absolute filepath in target root filesystem -**<placeholder>** - A string in the file which should be replaced. Usually some uppercase word - surrounded by @ signs -**<value>** - The value which should appear in the root filesystem instead of the - placeholder, could be some PTXCONF variable - -The ``install_replace`` macro can be used in targetinstall stage to adapt -some template and replace strings with content from menu variables or other -sources. For example look at the timezone you set in the ptxdist menu. An -``install_replace`` call in ``rules/timezone.make`` replaces the string -``@TIMEZONE@`` in the file ``/etc/timezone`` in root filesystem with the -content of the menu variable ``PTXCONF_TIMEZONE_LOCALTIME``. The file must -be installed with some other ``install_*`` command before -``install_replace`` can be used. A typical call would look like this: - -.. code-block:: make - - $(STATEDIR)/timezone.targetinstall: - ... - @$(call install_replace, timezone, /etc/timezone, @TIMEZONE@, \ - $(PTXCONF_TIMEZONE_LOCALTIME)) - -.. _param_macros: - -.. _ptxEndis: - -ptx/endis -~~~~~~~~~ - -To convert the state (set/unset) of a variable into an ``enable/disable`` -string use the ``ptx/endis`` macro. -If the given <variable> is set this macro expands to -the string ``enable``, if unset to ``disable`` instead. - -Usage: - -.. code-block:: none - - --$(call ptx/endis, <variable>)-<parameter> - -An example: - -.. code-block:: make - - FOO_CONF_OPT += --$(call ptx/endis,FOO_VARIABLE)-something - -Depending on the state of FOO_VARIABLE this line results into - -.. code-block:: make - - FOO_CONF_OPT += --enable-something (if FOO_VARIABLE is set) - FOO_CONF_OPT += --disable-something (if FOO_VARIABLE is unset) - -Refer :ref:`ptxDisen` for the opposite string expansion. - -.. _ptxDisen: - -ptx/disen -~~~~~~~~~ - -To convert the state (set/unset) of a variable into a ``disable/enable`` -string use the ``ptx/disen`` macro. -If the given <variable> is set this macro expands to -the string ``disable``, if unset to ``enable`` instead. - -Usage: - -.. code-block:: none - - --$(call ptx/disen, <variable>)-<parameter> - -An example: - -.. code-block:: make - - FOO_CONF_OPT += --$(call ptx/disen,FOO_VARIABLE)-something - -Depending on the state of FOO_VARIABLE this line results into - -.. code-block:: make - - FOO_CONF_OPT += --disable-something (if FOO_VARIABLE is set) - FOO_CONF_OPT += --enable-something (if FOO_VARIABLE is unset) - -Refer :ref:`ptxEndis` for the opposite string expansion. - -ptx/wwo -~~~~~~~ - -To convert the state (set/unset) of a variable into a ``with/without`` -string use the ``ptx/wwo`` macro. -If the given <variable> is set this macro expands to -the string ``with``, if unset to ``without`` instead. - -Usage: - -.. code-block:: none - - --$(call ptx/wwo, <variable>)-<parameter> - -An example: - -.. code-block:: make - - FOO_CONF_OPT += --$(call ptx/wwo,FOO_VARIABLE)-something - -Depending on the state of FOO_VARIABLE this line results into - -.. code-block:: make - - FOO_CONF_OPT += --with-something (if FOO_VARIABLE is set) - FOO_CONF_OPT += --without-something (if FOO_VARIABLE is unset) - -ptx/ifdef -~~~~~~~~~ - -To convert the state (set/unset) of a variable into one of two strings use the -``ptx/ifdef`` macro. -If the given <variable> is set this macro expands to -the first given string, if unset to the second given string. - -Usage: - -.. code-block:: make - - --with-something=$(call ptx/ifdef, <variable>, <first-string>, <second-string) - -An example: - -.. code-block:: make - - FOO_CONF_OPT += --with-something=$(call ptx/ifdef,FOO_VARIABLE,/usr,none) - -Depending on the state of FOO_VARIABLE this line results into - -.. code-block:: make - - FOO_CONF_OPT += --with-something=/usr (if FOO_VARIABLE is set) - FOO_CONF_OPT += --with-something=none (if FOO_VARIABLE is unset) - -ptx/truefalse -~~~~~~~~~~~~~ - -To convert the state (set/unset) of a variable into a ``true/false`` -string use the ``ptx/truefalse`` macro. -If the given <variable> is set this macro expands to -the string ``true``, if unset to ``false`` instead. - -Usage: - -.. code-block:: none - - -Dwith-something=$(call ptx/truefalse,<variable>) - -An example: - -.. code-block:: make - - FOO_CONF_OPT += -Dwith-something=$(call ptx/truefalse,<variable>) - -Depending on the state of FOO_VARIABLE this line results into - -.. code-block:: make - - FOO_CONF_OPT += -Dwith-something=true (if FOO_VARIABLE is set) - FOO_CONF_OPT += -Dwith-something=false (if FOO_VARIABLE is unset) - -ptx/get-alternative -~~~~~~~~~~~~~~~~~~~ - -This macro can be used to find files or directories in the BSP and PTXdist. -There are two arguments, **prefix** and **file**. The search path is very -similar to :ref:`install_alternative`. The first existing location of the -following paths is returned: - -* ``$(PTXDIST_WORKSPACE)/$(prefix)$(PTXDIST_PLATFORMSUFFIX)/$(file)`` -* ``$(PTXDIST_WORKSPACE)/$(prefix)/$(file)$(PTXDIST_PLATFORMSUFFIX)`` -* ``$(PTXDIST_PLATFORMCONFIGDIR)/$(prefix)/$(file)$(PTXDIST_PLATFORMSUFFIX)`` -* ``$(PTXDIST_WORKSPACE)/$(prefix)/$(file)`` -* ``$(PTXDIST_PLATFORMCONFIGDIR)/$(prefix)/$(file)`` -* ``$(PTXDIST_TOPDIR)/$(prefix)/$(file)`` - - -.. _in_path: - -ptx/in-path -~~~~~~~~~~~ - -This macro can be used to find files or directories in the BSP and PTXdist. -There are two arguments, **path variable** and **file**. The **path -variable** must be a variable name that is available in a shell called by -**make**. The variable must contain a ``:`` separated list of directories. -The **file** will be searched in these directories and the first existing -path is returned. PTXdist defines several variables that can be used here. -The directories are in the usual search order. - -- **PTXDIST_PATH_LAYERS** contains all layers from **PTXDIST_WORKSPACE** - to **PTXDIST_TOPDIR** - -- **PTXDIST_PATH** is like **PTXDIST_PATH_LAYERS** but also contains the - **PTXDIST_PLATFORMCONFIGDIR** for each layer. - -- **PTXDIST_PATH_SCRIPTS**, **PTXDIST_PATH_RULES** and - **PTXDIST_PATH_PLATFORMS** are like **PTXDIST_PATH** with the extra - ``scripts/``, ``rules/`` and ``platforms/`` subdirectory respectively. - -Hint: use the :ref:`print<command_print>` command to get the exact list of -directories for each of these variables. - -.. _in_platformconfigdir: - -ptx/in-platformconfigdir -~~~~~~~~~~~~~~~~~~~~~~~~ - -This macro is only useful with multiple layers. It has one argument -**file**. The **file** is searched for in the platform directory in -all layers in the usual search order. It returns the first existing file. -If none exists it returns ``$(PTXDIST_PLATFORMCONFIGDIR)/$(file)``. This -avoids unexpected errors due to empty variables if a file is missing. - -.. _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 - -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)/<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: - -.. code-block:: make - - $(<PKG>_SOURCE): - @$(call targetinfo) - @$(call get, <PKG>) - -extract Stage Default Rule -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If the *extract* stage is omitted, PTXdist runs instead: - -.. code-block:: make - - $(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 -: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)/<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: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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: - -.. code-block:: make - - $(STATEDIR)/<pkg>.compile: - @$(call targetinfo) - @$(call world/compile, <PKG>) - @$(call touch) - -Except in some corner cases, ``world/compile`` expands to something like -this: - -.. code-block:: sh - - cd ${<PKG>_DIR} && \ - ${<PKG>_PATH} ${<PKG>_MAKE_ENV} \ - ${MAKE} ${<PKG>_MAKE_OPT} ${PARALLELMFLAGS} - -The variables that are used here are described in the :ref:`Compile -Stage<vars_compile>` 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: - -.. code-block:: make - - $(STATEDIR)/<pkg>.install: - @$(call targetinfo) - @$(call world/install, <PKG>) - @$(call touch) - -Except in some corner cases, ``world/install`` expands to something like -this: - -.. code-block:: sh - - cd ${<PKG>_DIR} && \ - ${<PKG>_PATH} ${<PKG>_MAKE_ENV} \ - ${MAKE} ${<PKG>_INSTALL_OPT} - -The variables that are used here are described in the :ref:`Install -Stage<vars_install>` section of the variable reference. - -At the end of this stage, all relevant files must be installed in the -:ref:`package install directory<pkg_pkgdir>`. - -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<devpkgs>` -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<devpkgs>` 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<pkg_pkgdir>` -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)/<pkg>.<stage_to_skip>: - @$(call targetinfo) - @$(call touch) - -Replace the <stage_to_skip> by ``get``, ``extract``, ``prepare``, -``compile``, ``install`` or ``targetinstall``. +.. include:: ref_make_variables.inc +.. include:: ref_make_macros.inc +.. include:: ref_rule_file_layout.inc .. _ptxdist_parameter_reference: diff --git a/doc/ref_rule_file_layout.inc b/doc/ref_rule_file_layout.inc new file mode 100644 index 000000000000..ea7eb8c4903d --- /dev/null +++ b/doc/ref_rule_file_layout.inc @@ -0,0 +1,261 @@ +.. _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 + +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)/<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: + +.. code-block:: make + + $(<PKG>_SOURCE): + @$(call targetinfo) + @$(call get, <PKG>) + +extract Stage Default Rule +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the *extract* stage is omitted, PTXdist runs instead: + +.. code-block:: make + + $(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 +: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)/<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: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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: + +.. code-block:: make + + $(STATEDIR)/<pkg>.compile: + @$(call targetinfo) + @$(call world/compile, <PKG>) + @$(call touch) + +Except in some corner cases, ``world/compile`` expands to something like +this: + +.. code-block:: sh + + cd ${<PKG>_DIR} && \ + ${<PKG>_PATH} ${<PKG>_MAKE_ENV} \ + ${MAKE} ${<PKG>_MAKE_OPT} ${PARALLELMFLAGS} + +The variables that are used here are described in the :ref:`Compile +Stage<vars_compile>` 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: + +.. code-block:: make + + $(STATEDIR)/<pkg>.install: + @$(call targetinfo) + @$(call world/install, <PKG>) + @$(call touch) + +Except in some corner cases, ``world/install`` expands to something like +this: + +.. code-block:: sh + + cd ${<PKG>_DIR} && \ + ${<PKG>_PATH} ${<PKG>_MAKE_ENV} \ + ${MAKE} ${<PKG>_INSTALL_OPT} + +The variables that are used here are described in the :ref:`Install +Stage<vars_install>` section of the variable reference. + +At the end of this stage, all relevant files must be installed in the +:ref:`package install directory<pkg_pkgdir>`. + +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<devpkgs>` +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<devpkgs>` 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<pkg_pkgdir>` +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)/<pkg>.<stage_to_skip>: + @$(call targetinfo) + @$(call touch) + +Replace the <stage_to_skip> by ``get``, ``extract``, ``prepare``, +``compile``, ``install`` or ``targetinstall``. + + -- 2.20.1 _______________________________________________ ptxdist mailing list [email protected]
