scons_gd/scons/SCons/Tool/packaging/packaging.xml

<?xml version="1.0"?>
<!--
__COPYRIGHT__

This file is processed by the bin/SConsDoc.py module.
See its __doc__ string for a discussion of the format.
-->

<!DOCTYPE sconsdoc [
<!ENTITY % scons SYSTEM '../../../doc/scons.mod'>
%scons;
<!ENTITY % builders-mod SYSTEM '../../../doc/generated/builders.mod'>
%builders-mod;
<!ENTITY % functions-mod SYSTEM '../../../doc/generated/functions.mod'>
%functions-mod;
<!ENTITY % tools-mod SYSTEM '../../../doc/generated/tools.mod'>
%tools-mod;
<!ENTITY % variables-mod SYSTEM '../../../doc/generated/variables.mod'>
%variables-mod;
]>

<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">

<tool name="packaging">
<summary>
<para>
Sets construction variables for the &b-link-Package; Builder.
If this tool is enabled, the <option>--package-type</option>
command-line option is also enabled.
</para>
</summary>
<sets>
</sets>
<uses>
</uses>
</tool>

<builder name="Package">
<summary>
<para>
Builds software distribution packages.
A <firstterm>package</firstterm> is a container format which
includes files to install along with metadata.
Packaging is optional, and must be enabled by specifying
the &t-link-packaging; tool. For example:
</para>

<example_commands>
env = Environment(tools=['default', 'packaging'])
</example_commands>

<para>
&SCons; can build packages in a number of well known packaging formats.
The target package type may be selected with the
the &cv-link-PACKAGETYPE; construction variable
or the <option>--package-type</option> command line option.
The package type may be a list, in which case &SCons; will attempt
to build packages for each type in the list. Example:
</para>

<example_commands>
env.Package(PACKAGETYPE=['src_zip', 'src_targz'], <replaceable>...other args...</replaceable>)
</example_commands>

<para>
The currently supported packagers are:
</para>

<informaltable rowsep="1" colsep="1" frame="topbot">
<tgroup cols="2">
<tbody>
<row><entry><literal>msi</literal></entry><entry>Microsoft Installer package</entry></row>
<row><entry><literal>rpm</literal></entry><entry>RPM Package Manger package</entry></row>
<row><entry><literal>ipkg</literal></entry><entry>Itsy Package Management package</entry></row>
<row><entry><literal>tarbz2</literal></entry><entry>bzip2-compressed tar file</entry></row>
<row><entry><literal>targz</literal></entry><entry>gzip-compressed tar file</entry></row>
<row><entry><literal>tarxz</literal></entry><entry>xz-compressed tar file</entry></row>
<row><entry><literal>zip</literal></entry><entry>zip file</entry></row>
<row><entry><literal>src_tarbz2</literal></entry><entry>bzip2-compressed tar file suitable as source to another packager</entry></row>
<row><entry><literal>src_targz</literal></entry><entry>gzip-compressed tar file suitable as source to another packager</entry></row>
<row><entry><literal>src_tarxz</literal></entry><entry>xz-compressed tar file suitable as source to another packager</entry></row>
<row><entry><literal>src_zip</literal></entry><entry>zip file suitable as source to another packager</entry></row>
</tbody>
</tgroup>
</informaltable>

<para>
The file list to include in the package may be specified with
the &source; keyword argument. If omitted,
the &f-link-FindInstalledFiles; function is called behind the scenes
to select all files that have an &b-link-Install;, &b-link-InstallAs;
or &b-link-InstallVersionedLib; Builder attached.
If the &target; keyword argument is omitted, the target name(s)
will be deduced from the package type(s).
</para>

<para>
The metadata comes partly from attributes of the files to be packaged,
and partly from packaging <firstterm>tags</firstterm>.
Tags can be passed as keyword arguments
to the &b-Package; builder call,
and may also be attached to files
(or more accurately, Nodes representing files)
with the &f-link-Tag; function.
Some package-level tags are mandatory, and will lead to errors if omitted.
The mandatory tags vary depending on the package type.
<!-- TODO: should document which tags are mandatory for which packager -->
</para>

<para>
While packaging, the builder uses a temporary location named
by the value of the &cv-link-PACKAGEROOT; variable -
the package sources are copied there before packaging.
</para>

<para>
Packaging example:
</para>

<example_commands>
env = Environment(tools=["default", "packaging"])
env.Install("/bin/", "my_program")
env.Package(
    NAME="foo",
    VERSION="1.2.3",
    PACKAGEVERSION=0,
    PACKAGETYPE="rpm",
    LICENSE="gpl",
    SUMMARY="balalalalal",
    DESCRIPTION="this should be really really long",
    X_RPM_GROUP="Application/fu",
    SOURCE_URL="https://foo.org/foo-1.2.3.tar.gz",
)
</example_commands>

<para>
In this example, the target <filename>/bin/my_program</filename>
created by the &b-Install; call would not be built by default
since it is not under the project top directory.
However, since no <parameter>source</parameter>
is specified to the &b-Package; builder,
it is selected for packaging by the default sources rule.
Since packaging is done using &cv-link-PACKAGEROOT;, no write is
actually done to the system's <filename>/bin</filename> directory,
and the target <emphasis>will</emphasis> be selected since
after rebasing to underneath &cv-PACKAGEROOT; it is now under
the top directory of the project.
</para>

</summary>
</builder>

<cvar name="ARCHITECTURE">
<summary>
<para>
Specifies the system architecture for which
the package is being built.
The default is the system architecture
of the machine on which SCons is running.
This is used to fill in the
<literal>Architecture:</literal>
field in an Ipkg
<filename>control</filename> file,
and the <literal>BuildArch:</literal> field
in the RPM <filename>.spec</filename> file,
as well as forming part of the name of a generated RPM package file.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>

<cvar name="CHANGE_SPECFILE">
<summary>
<para>
A hook for modifying the file that controls the packaging build
(the <filename>.spec</filename> for RPM,
the <filename>control</filename> for Ipkg,
the <filename>.wxs</filename> for MSI).
If set, the function will be called
after the SCons template for the file has been written.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>

<cvar name="CHANGELOG">
<summary>
<para>
The name of a file containing the change log text
to be included in the package.
This is included as the
<literal>%changelog</literal>
section of the RPM
<filename>.spec</filename> file.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>

<cvar name="DESCRIPTION">
<summary>
<para>
A long description of the project being packaged.
This is included in the relevant section
of the file that controls the packaging build.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>

<cvar name="DESCRIPTION_lang">
<summary>
<para>
A language-specific long description for
the specified <varname>lang</varname>.
This is used to populate a
<literal>%description -l</literal>
section of an RPM
<filename>.spec</filename> file.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>

<cvar name="LICENSE">
<summary>
<para>
The abbreviated name, preferably the SPDX code, of the license under which
this project is released (GPL-3.0, LGPL-2.1, BSD-2-Clause etc.).
See
<ulink url="http://www.opensource.org/licenses/alphabetical">
http://www.opensource.org/licenses/alphabetical</ulink>
for a list of license names and SPDX codes.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>

<cvar name="NAME">
<summary>
<para>
Specfies the name of the project to package.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>

<cvar name="PACKAGEROOT">
<summary>
<para>
Specifies the directory where all files in resulting archive will be
placed if applicable.  The default value is <quote>&cv-NAME;-&cv-VERSION;</quote>.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>

<cvar name="PACKAGETYPE">
<summary>
<para>
Selects the package type to build when using the &b-link-Package;
builder. May be a string or list of strings. See the docuentation
for the builder for the currently supported types.
</para>

<para>
&cv-PACKAGETYPE; may be overridden with the <option>--package-type</option>
command line option.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>

<cvar name="PACKAGEVERSION">
<summary>
<para>
The version of the package (not the underlying project).
This is currently only used by the rpm packager
and should reflect changes in the packaging,
not the underlying project code itself.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>

<cvar name="SOURCE_URL">
<summary>
<para>
The URL
(web address)
of the location from which the project was retrieved.
This is used to fill in the
<literal>Source:</literal>
field in the controlling information for Ipkg and RPM packages.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>

<cvar name="SUMMARY">
<summary>
<para>
A short summary of what the project is about.
This is used to fill in the
<literal>Summary:</literal>
field in the controlling information for Ipkg and RPM packages,
and as the
<literal>Description:</literal>
field in MSI packages.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>

<cvar name="VENDOR">
<summary>
<para>
The person or organization who supply the packaged software.
This is used to fill in the
<literal>Vendor:</literal>
field in the controlling information for RPM packages,
and the
<literal>Manufacturer:</literal>
field in the controlling information for MSI packages.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>

<cvar name="VERSION">
<summary>
<para>
The version of the project, specified as a string.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>


<cvar name="X_IPK_DEPENDS">
<summary>
<para>
This is used to fill in the
<literal>Depends:</literal>
field in the controlling information for Ipkg packages.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>

<cvar name="X_IPK_DESCRIPTION">
<summary>
<para>
This is used to fill in the
<literal>Description:</literal>
field in the controlling information for Ipkg packages.
The default value is
<quote>&cv-SUMMARY;\n&cv-DESCRIPTION;</quote>
</para>
</summary>
</cvar>

<cvar name="X_IPK_MAINTAINER">
<summary>
<para>
This is used to fill in the
<literal>Maintainer:</literal>
field in the controlling information for Ipkg packages.
</para>
</summary>
</cvar>

<cvar name="X_IPK_PRIORITY">
<summary>
<para>
This is used to fill in the
<literal>Priority:</literal>
field in the controlling information for Ipkg packages.
</para>
</summary>
</cvar>

<cvar name="X_IPK_SECTION">
<summary>
<para>
This is used to fill in the
<literal>Section:</literal>
field in the controlling information for Ipkg packages.
</para>
</summary>
</cvar>

<cvar name="X_MSI_LANGUAGE">
<summary>
<para>
This is used to fill in the
<literal>Language:</literal>
attribute in the controlling information for MSI packages.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>

<cvar name="X_MSI_LICENSE_TEXT">
<summary>
<para>
The text of the software license in RTF format.
Carriage return characters will be
replaced with the RTF equivalent \\par.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>

<cvar name="X_MSI_UPGRADE_CODE">
<summary>
<para>
TODO
</para>
</summary>
</cvar>


<cvar name="X_RPM_AUTOREQPROV">
<summary>
<para>
This is used to fill in the
<literal>AutoReqProv:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
<para>See the &b-link-Package; builder.</para>
</summary>
</cvar>

<cvar name="X_RPM_BUILD">
<summary>
<para>
internal, but overridable
</para>
</summary>
</cvar>

<cvar name="X_RPM_BUILDREQUIRES">
<summary>
<para>
This is used to fill in the
<literal>BuildRequires:</literal>
field in the RPM
<filename>.spec</filename> file.
Note this should only be used on a host managed by rpm as the dependencies will not be resolvable at build time otherwise.
</para>
</summary>
</cvar>

<cvar name="X_RPM_BUILDROOT">
<summary>
<para>
internal, but overridable
</para>
</summary>
</cvar>

<cvar name="X_RPM_CLEAN">
<summary>
<para>
internal, but overridable
</para>
</summary>
</cvar>

<cvar name="X_RPM_CONFLICTS">
<summary>
<para>
This is used to fill in the
<literal>Conflicts:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</summary>
</cvar>

<cvar name="X_RPM_DEFATTR">
<summary>
<para>
This value is used as the default attributes
for the files in the RPM package.
The default value is
<quote>(-,root,root)</quote>.
</para>
</summary>
</cvar>

<cvar name="X_RPM_DISTRIBUTION">
<summary>
<para>
This is used to fill in the
<literal>Distribution:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</summary>
</cvar>

<cvar name="X_RPM_EPOCH">
<summary>
<para>
This is used to fill in the
<literal>Epoch:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</summary>
</cvar>

<cvar name="X_RPM_EXCLUDEARCH">
<summary>
<para>
This is used to fill in the
<literal>ExcludeArch:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</summary>
</cvar>

<cvar name="X_RPM_EXLUSIVEARCH">
<summary>
<para>
This is used to fill in the
<literal>ExclusiveArch:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</summary>
</cvar>

<cvar name="X_RPM_EXTRADEFS">
<summary>
<para>
A list used to supply extra defintions or flags
to be added to the RPM <filename>.spec</filename> file.
Each item is added as-is with a carriage return appended.
This is useful if some specific RPM feature not otherwise
anticipated by SCons needs to be turned on or off.
Note if this variable is omitted, SCons will by
default supply the value
<literal>'%global debug_package %{nil}'</literal>
to disable debug package generation.
To enable debug package generation, include this
variable set either to None, or to a custom
list that does not include the default line.
Added in version 3.1.
</para>

<example_commands>
env.Package(
    NAME="foo",
    ...
    X_RPM_EXTRADEFS=[
        "%define _unpackaged_files_terminate_build 0"
        "%define _missing_doc_files_terminate_build 0"
    ],
    ...
)
</example_commands>

</summary>
</cvar>

<cvar name="X_RPM_GROUP">
<summary>
<para>
This is used to fill in the
<literal>Group:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</summary>
</cvar>

<cvar name="X_RPM_GROUP_lang">
<summary>
<para>
This is used to fill in the
<literal>Group(lang):</literal>
field in the RPM
<filename>.spec</filename> file.
Note that
<varname>lang</varname>
is not literal
and should be replaced by
the appropriate language code.
</para>
</summary>
</cvar>

<cvar name="X_RPM_ICON">
<summary>
<para>
This is used to fill in the
<literal>Icon:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</summary>
</cvar>

<cvar name="X_RPM_INSTALL">
<summary>
<para>
internal, but overridable
</para>
</summary>
</cvar>

<cvar name="X_RPM_PACKAGER">
<summary>
<para>
This is used to fill in the
<literal>Packager:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</summary>
</cvar>

<cvar name="X_RPM_PROVIDES">
<summary>
<para>
This is used to fill in the
<literal>Provides:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</summary>
</cvar>

<cvar name="X_RPM_POSTINSTALL">
<summary>
<para>
This is used to fill in the
<literal>%post:</literal>
section in the RPM
<filename>.spec</filename> file.
</para>
</summary>
</cvar>

<cvar name="X_RPM_PREINSTALL">
<summary>
<para>
This is used to fill in the
<literal>%pre:</literal>
section in the RPM
<filename>.spec</filename> file.
</para>
</summary>
</cvar>

<cvar name="X_RPM_PREFIX">
<summary>
<para>
This is used to fill in the
<literal>Prefix:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</summary>
</cvar>

<cvar name="X_RPM_PREP">
<summary>
<para>
internal, but overridable
</para>
</summary>
</cvar>

<cvar name="X_RPM_POSTUNINSTALL">
<summary>
<para>
This is used to fill in the
<literal>%postun:</literal>
section in the RPM
<filename>.spec</filename> file.
</para>
</summary>
</cvar>

<cvar name="X_RPM_PREUNINSTALL">
<summary>
<para>
This is used to fill in the
<literal>%preun:</literal>
section in the RPM
<filename>.spec</filename> file.
</para>
</summary>
</cvar>

<cvar name="X_RPM_REQUIRES">
<summary>
<para>
This is used to fill in the
<literal>Requires:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</summary>
</cvar>

<cvar name="X_RPM_SERIAL">
<summary>
<para>
This is used to fill in the
<literal>Serial:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</summary>
</cvar>

<cvar name="X_RPM_URL">
<summary>
<para>
This is used to fill in the
<literal>Url:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</summary>
</cvar>


<!--

THE FOLLOWING AREN'T CONSTRUCTION VARIABLES,
THEY'RE "TAGS" THAT CAN BE ATTACHED
TO DIFFERENT FILES OR DIRECTORIES.
NOT SURE YET WHAT TO DO ABOUT THESE.

<cvar name="CONFIG">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

<cvar name="CONFIG_NOREPLACE">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

<cvar name="DOC">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

<cvar name="INSTALL_LOCATION">
<summary>
<para>
internal, but overridable, TODO
</para>
</summary>
</cvar>

<cvar name="LANG_lang">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

<cvar name="UNIX_ATTR">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

<cvar name="X_IPK_POSTINST">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

<cvar name="X_IPK_POSTRM">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

<cvar name="X_IPK_PREINST">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

<cvar name="X_IPK_PRERM">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

<cvar name="X_MSI_FEATURE">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

<cvar name="X_MSI_FILEID">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

<cvar name="X_MSI_LONGNAME">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

<cvar name="X_MSI_SHORTNAME">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

<cvar name="X_MSI_VITAL">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

<cvar name="X_RPM_DIR">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

<cvar name="X_RPM_DOCDIR">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

<cvar name="X_RPM_GHOST">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

<cvar name="X_RPM_VERIFY">
<summary>
<para>
TODO
</para>
</summary>
</cvar>

-->


<scons_function name="Tag">
<arguments signature="global">
(node, tags)
</arguments>
<summary>
<para>
Annotates file or directory Nodes with
information about how the
&b-link-Package;
Builder should package those files or directories.
All Node-level tags are optional.
</para>

<para>
Examples:
</para>

<example_commands>
# makes sure the built library will be installed with 644 file access mode
Tag(Library('lib.c'), UNIX_ATTR="0o644")

# marks file2.txt to be a documentation file
Tag('file2.txt', DOC)
</example_commands>
</summary>
</scons_function>


<!--
<function name="FindSourceFiles">
<summary>
<para>
A convenience function which returns all leaves of the build tree.
</para>
</summary>
</function>

<builder name="FindInstalledFiles">
<summary>
<para>
Returns all files "built" by the &b-Install; or &b-InstallAs; builders.
</para>
</summary>
</function>
-->

</sconsdoc>