Build System Packaging Module

Overview

The Build System Packaging Module provides the build system with the ability to create various packagings of files. This includes the ability to create tar files, zip files, etc.

NOTE: Due to limitations in gmake's ability to interpret generated dependency chains on the fly, making some of the package targets in a fresh tree may not work in the first invocation even though the dependencies have been mapped out. To work around this problem is is recommended that an 'all' or 'depends' build be invoked separately before any of the targets provided by this module are requested.

Macros and Controls

PACKAGE_ROOT: The root of the directory for some packaging module targets. The default value for this is $(COMPONENT_ROOT)/package.
PACKAGE_TARGET_DIR: The target directory for some package targets. Package targets share a component wide target directory so component packages can by built up here piece by piece as the build progresses through the component source tree. The default value for this is $(PACKAGE_ROOT)/built/$(BS_PLATFORM_ARCH_FULL).
PACKAGE_RELEASE_DIR: A final staging dir for deliverable tarballs, bundled package, and files. The default value for this is $(PACKAGE_ROOT)/release/$(BS_PLATFORM_ARCH_FULL). The distinction between this and pushing components to dist is fuzzy.

Functions

PACKAGING_FUNC_GET_TARGZ_REALTARGET
PACKAGING_FUNC_GET_TARGZ_FLAGTARGET
PACKAGING_FUNC_GET_ZIP_REALTARGET
PACKAGING_FUNC_GET_ZIP_FLAGTARGET

PACKAGEFILE_TARGETS

PACKAGEFILE_TARGETS Overview

PACKAGEFILE_TARGETS is the pattern target used to package files from a build into the component wide package directory for eventual component roll up. In essence, PACKAGEFILE_TARGETS is a glorified interface to the file copy command. Only files may be packaged with this pattern target; directories should be packaged with the PACKAGEDIR_TARGETS pattern target. By default, the file packaged by a given PACKAGEFILE_TARGETS pattern target will be <package file target> found in either the target dir for the build system's platform or the default native code tool chain's target platform. This may be overridden by the <package file target> <package file target>_FROM option.

PACKAGEFILE_TARGETS will be built during the "posttarget" phase of a build. PACKAGEFILE_TARGETS may be built in isolation by requesting the "packaging_packagefile" target.

PACKAGEFILE_TARGETS Options

<package file target>_DEST: Specifies the file name and path under $(PACKAGE_TARGET_DIR) to copy the <package file target> to. This option must specify a file location and not a directory. The default value is simply <package file target>.
<package file target>_FROM: Override the entire default source path to the <package file target>. Setting this option makes renders the _PLATFORM option moot. This option can be used with a <package file target> to achieve the same behavior provided by the PACKAGE_RAW_TARGETS of the old build system.
<package file target>_DEP: Specify additional dependancies for the current target.

PACKAGEDIR_TARGETS

PACKAGEDIR_TARGETS Overview

PACKAGEDIR_TARGETS is the pattern target used to package directories from a build into the component wide package directory for eventual component roll up. Only directories may be packaged with this pattern target; files should be packaged with the PACKAGEFILE_TARGETS pattern target. By default, the directory packaged by a given PACKAGEDIR_TARGETS pattern target will be <package dir target> found in either the target dir for the build system's platform or the default native code tool chain's target platform. This may be overridden by the <package dir target> <package dir target>_FROM option.

PACKAGEDIR_TARGETS will be built during the "posttarget" phase of a build. PACKAGEDIR_TARGETS may be built in isolation by requesting the "packaging_packagedir" target.

WARNING: PACKAGEDIR_TARGETS pattern targets WILL NOT be cleaned by building the "clean" target. These pattern targets will only be cleaned by building the "nuke" target. Furthermore, these targets will be remade with every build of the "posttarget" phase. These are side effects of directory targets potentially overlapping, and of not having their full contents enumerated to the build system for dependancy resolution.

PACKAGEDIR_TARGETS Options

<package dir target>_DEST: Specifies the directory name and path under $(PACKAGE_TARGET_DIR) to copy the <package dir target> to. This option must specify a directory name. The default value is the basename of the current target. If the target already exists, the current target will be overlayed into the existing directory.
<package dir target>_FROM: Override the entire default source path to the <package dir target>. Setting this option makes renders the _PLATFORM option moot. This option can be used with a <package dir target> to achieve the same behavior provided by the PACKAGE_RAW_TARGETS of the old build system.
<package dir target>_SCRUB: Specifies a list of files or directories to remove from the package once it has been copied to the $(PACKAGE_TARGET_DIR). This option is useful for cleaning out CVS directories or other ancillary files when packaging directories. WARNING:Use of the _SCRUB option for PACKAGEDIR_TARGETS may have unintended consequences when multiple targets overlay into the same directory.
<package dir target>_DEP: Specify additional dependancies for the current target.

TARGZ_TARGETS

TARGZ_TARGETS Overview

TARGZ_TARGETS is the pattern target used to create tar'ed and gzip'ed archive files. By default, the archive will be created in a file named $(BS_ARCH_TARGET_DIR)/<targz target>.tar.gz, but this may be overridden by target specific controls.

TARGZ_TARGETS will be built during the "posttarget" phase of a build. TARGZ_TARGETS may be built in isolation by requesting the "packaging_targz" target.

TARGZ_TARGETS Options

<targz target>_DEST: Specify an override location for the archive file produced by the evaluation of the pattern rules. The default archive file will be $(BS_ARCH_TARGET_DIR)/<targz target>.tar.gz,rules, but specifying paths under the $(PACKAGE_TARGET_DIR) or $(PACKAGE_STAGE_DIR) may be useful for producing archive files for final component delivery.
<targz target>_FILES: Specify a list of files to include in the archive.
<targz target>_MANIFEST: Specify a manifest file containing a list of files to include in the archive. The contents of the manifest are treated as if they appeared in the _FILES option.
<targz target>_CWD: The parent directory of the files specified by the _FILES or _MANIFEST options. Files to appear in a given <targz target> archive must be located under the directory specified by the _CWD option, and will have the _CWD directory prefix stripped prior to being placed in the archive. The default value for the _CWD option is the target directory $(BS_ARCH_TARGET_DIR), but it is expected that values containing $(PACKAGE_TARGET_DIR) will be useful.

ZIP_TARGETS

ZIP_TARGETS Overview

ZIP_TARGETS is the pattern target used to create zip archive files. By default, the archive will be created in a file named $(BS_ARCH_TARGET_DIR)/<zip target>.zip, but this may be overridden by target specific controls.

ZIP_TARGETS will be built during the "posttarget" phase of a build. ZIP_TARGETS may be built in isolation by requesting the "packaging_zip" target.

ZIP_TARGETS Options

<zip target>_DEST: Specify an override location for the archive file produced by the evaluation of the pattern rules. The default archive file will be $(BS_ARCH_TARGET_DIR)/<zip target>.tar.gz,rules, but specifying paths under the $(PACKAGE_TARGET_DIR) or $(PACKAGE_STAGE_DIR) may be useful for producing archive files for final component delivery.
<zip target>_FILES: Specify a list of files to include in the archive.
<zip target>_MANIFEST: Specify a manifest file containing a list of files to include in the archive. The contents of the manifest are treated as if they appeared in the _FILES option.
<zip target>_CWD: The parent directory of the files specified by the _FILES or _MANIFEST options. Files to appear in a given <zip target> archive must be located under the directory specified by the _CWD option, and will have the _CWD directory prefix stripped prior to being placed in the archive. The default value for the _CWD option is the target directory $(BS_ARCH_TARGET_DIR), but it is expected that values containing $(PACKAGE_TARGET_DIR) will be useful.

packaging_packagefile

packaging_packagefile Overview

Simple target to trigger the building of PACKAGEFILE_TARGETS pattern targets independent of the main build "posttarget" phase.

packaging_packagedir

packaging_packagedir Overview

Simple target to trigger the building of PACKAGEDIR_TARGETS pattern targets independent of the main build "posttarget" phase.

packaging_targz

packaging_targz Overview

Simple target to trigger the building of TARGZ_TARGETS pattern targets independent of the main build "posttarget" phase.

packaging_zip

packaging_zip Overview

Simple target to trigger the building of ZIP_TARGETS pattern targets independent of the main build "posttarget" phase.

packaging_info

packaging_info Overview

Simple target to display information about the macro settings of all global macros used by the packaging module of the build system. The packaging_info target will be built during the "info" phase of a build, and can be built in isolation by requesting the packaging_info target.

packaging_man

packaging_man Overview

Simple target to display usage information and help pertaining to the packaging module of the build system. The packaging_man target will be built during the "man" phase of a build, and can be built in isolation by requesting the packaging_man target.

PACKAGING_FUNC_GET_TARGZ_REALTARGET

This function is provided to translate a targz pattern target as it is named in the TARGZ_TARGETS list to the real target that results from the pattern rules.

PACKAGING_FUNC_GET_TARGZ_FLAGTARGET

This function is provided to translate a targz pattern target as it is named in the TARGZ_TARGETS list to the flag target that is used to track dependencies on a given targz pattern target. This flag target is probably of little use outside the the internals of the packaging build system module, since PACKAGING_FUNC_GET_TARGZ_REALTARGET provides a better candidate for chaining a target target in the dependency list of another pattern target.

PACKAGING_FUNC_GET_ZIP_REALTARGET

This function is provided to translate a zip pattern target as it is named in the ZIP_TARGETS list to the real target that results from the pattern rules.

PACKAGING_FUNC_GET_ZIP_FLAGTARGET

This function is provided to translate a zip pattern target as it is named in the ZIP_TARGETS list to the flag target that is used to track dependencies on a given zip pattern target. This flag target is probably of little use outside the the internals of the packaging build system module, since PACKAGING_FUNC_GET_ZIP_REALTARGET provides a better candidate for chaining a target target in the dependency list of another pattern target.

Example Makefile


COMPONENT_ROOT=../..
BS_ROOT=$(COMPONENT_ROOT)/../build3

include $(BS_ROOT)/defines.mk


#
# The resulting package isn't really useful, just shows how you can use the target options
#

moof_pkg_target=moof-tar1.tar.gz

PACKAGEDIR_TARGETS=foo-pkg1 $(moof_pkg_target)
TARGZ_TARGETS=moof-tar1


foo-pkg1_FROM=$(COMPONENT_ROOT)/sample-srcdir
#foo-pkg1_DEST=$(PROJECT)
foo-pkg1_SCRUB=CVS

moof-tar1_FILES=foo-pkg1
moof-tar1_CWD=$(PACKAGE_TARGET_DIR)

#$(moof_pkg_target)_FROM=$(BS_ARCH_TARGET_DIR)/moof-tar1.tar.gz # This is the default
$(moof_pkg_target)_DEST=moof-tarball-package-dir/


include $(BS_ROOT)/rules.mk