The host-based command-line bundle tool is used to create bundle format images, as well as add and delete items, list and verify the contents, extract data, and other relevant commands.

Usage: bundle [option(s)] <bundlefilename> [cmds]

For a full list of the bundle tool's options and commands use the --help option:

$ bundle --help

The <bundlefilename> should always be supplied. The default behaviour if no operations are specified is to verify the <bundlefilename> and list its contents.

Explicit parameter options are case-insensitive. e.g. When providing a hash value either MD5 or md5 are acceptable and identical in their result.

The command-line bundle parameters are processed left to right, with parameters for operations following the command. The following examples are identical in the result produced:

$ bundle testbundle_minimum_md5.bin create hash md5

$ bundle testbundle_minimum_md5.bin hash md5 create

Both examples would create a bundle file testbundle_minimum_md5.bin that incorporates an md5 hash.

The following example creates a bundle called egbundle.bin. The bundle has a signature of 0x1 and includes bundle metadata from the manifest.txt. The entire bundle's contents will be covered by an sha256-based hash. The bundle would contain a single compressed item identified by a tag of 0x2. The item's data comes from short.bin and its metadata from itemarb.txt. The item's contents including the tag, metadata, and compressed data will be covered by an md5 hash. Note that as the item includes compressed data an additional md5 hash for the uncompressed data would also be incorporated.

$ bundle egbundle.bin create hash sha256 signature 0x01 arbitrary manifest.txt add \
        0x0002:short.bin:compress:md5:itemarb.txt

The bundle tool's add command is quite flexible in its usage. It has a single parameter describing the item to be added, with multiple fields separated by ':' characters. Only the tag and srcfile are required, with other optional fields specifying whether the source file should be compressed, whether or not a hash should be added and finally what metadata, if any, is to be included with the item.

add tag:srcfile[:[compress][:hash[:arbitrarymetadata]]]

The tag value of 0x0000 is reserved for the system, with all other tag values being available for application use. This gives a maximum possible bundle item count of 65635 items, which is unlikely to be a limitation for embedded targets. Most bundles will contain a small (<10) number of items, e.g. the main target application, FPGA initialisation data, device initialisation tables, etc.

add command examples:

Uncompressed, no hash

add 0x0001:datafile

Compressed, no hash

add 0x2:dfile:compress

Compressed, MD5 hash

add 11:dfile:c:md5

Uncompressed, CRC-32 hash with arbitrary data

add 0xF:dfile::crc32:textfile

Compressed, no hash with arbitrary data

add 2:dfile:C::textfile

The --commands option allows for a fixed set of bundle operations to be held in a file, rather than being passed individually as command line options to the tool. Individual operations (e.g. command name and its required arguments) should NOT be split across lines, but multiple lines are allowed. Lines that start with '#' as the first non-whitespace character are treated as comments, and ignored.

	Note
	No item metadata add commands are included since we can use “extract” to get data and then “delete” and re-“add” with the required arbitrary file if required.

	Warning
	Filenames in commands cannot contain ':' since it is used as a field delimiter in the <item> description.

The bundle package includes the complete sources for the host tool. eCosPro releases include a pre-built version of the tool for either Linux or Windows as appropriate. If needed the tool can be built from the supplied source, with the only non-standard-library dependency being the “zlib” library. Linux systems will normally provide “zlib” as standard, though it is easily built if required for other host systems.