Reference guide26Archive and Packaging Tools

Packages files so that their RISC OS filetypes, timestamps, attributes, and filename forms survive transfer and extraction. The wrapper drives the underlying rozipfile tool in archive-creation mode.

Pass files or directories after the archive name. Directory trees are traversed automatically, so a single application or source tree can be archived in one command.

The RISC OS-specific ZIP extra fields and the alternate NFS filename encoding are summarised in ../appendix/riscos-zip-file-format.

Lists or extracts ZIP archives while restoring RISC OS-aware filename and filetype information. The wrapper chooses the underlying mode from the first option supplied: -l lists, -t prints recovery SetType commands, and any other form extracts.

Any names after the archive limit extraction to selected members. Plain riscos-unzip archive.zip extracts the whole archive.

For the ZIP extension details understood by the wrapper, see ../appendix/riscos-zip-file-format.

Works with Spark and ArcFS archives. In this environment it is most often used to extract files with -x or -u, list contents with -l, or test integrity with -t.

Any names after the archive limit the action to selected members.

If you omit -u, -x, -l, and -t, the underlying tool reports archiving not supported in this version and exits without writing anything. This build of riscos-nspark supports only extraction, listing, and testing of existing Spark and ArcFS archives; it cannot create or update one.

Decompresses a single Squash-compressed file rather than a multi-file archive. This is commonly used on older compressed resources, ROM images, or source files distributed as one compressed object.

The Squash wrapper format and its embedded compress-style LZW payload are summarised in Appendix L: Squash file format.

Wraps the Python TBAFS extractor included in the environment. list reports contents, extract restores files to the host filesystem or to an ADFS image, types prints SetType recovery commands, and info reports header-level archive information.

The types and info forms take just the command name and archive path. The documented command-specific options belong to the list and extract forms.

The TBAFS archive structure and compression records are summarised in ../appendix/tbafs-file-format.

riscos-makealf creates new ALF object libraries, unpacks members from existing libraries, and renames members as it does so. It is most useful when you need more control over member naming than riscos-libfile provides, or when you want to combine ordinary object files and members extracted from existing libraries in a single operation.

Inputs are not limited to plain files. A member inside an existing library is written as library|member. Member wildcards are richer than normal filesystem wildcards: # matches one non-directory character, * matches a run of non-directory characters, and ** matches any sequence of characters. A common pattern such as mylib|** means every member in the library.

-i listfile reads more object names from a file, one per line, with blank lines and lines beginning with # ignored as comments. This is the practical way to handle long object lists. The output is normally a new ALF library, but if -o names a directory then the selected objects are written out as ordinary files in that directory instead. The warning text printed on failure mentions "with directory creation", but the tool does not actually create the intermediate subdirectories implied by a member's own path (such as o32.main); pre-create that subdirectory structure under the -o directory yourself, or the copy fails with couldn't open output object file.

Name control is one of the tool's main features. -b strips the leading library| part from extracted member names. -x from to defines one translation rule, and -X file reads multiple translation rules from a file. If several rules match, the one with the longer from string wins. -u makes the command fail rather than writing two outputs with the same final name.

-s translates Unix-style names such as foo.o to RISC OS-style o.foo. -l applies UnixLib-style filename translation instead, and takes precedence over -s. -n writes all timestamps as zero bytes, which is useful for reproducible output or convergence testing. -q suppresses progress output.

If the first command-line argument is +libfile+, or if the tool is invoked under a name ending in libfile, it attempts to interpret the rest of the command line using a partial libfile-compatible syntax. This compatibility mode is useful when a build expects libfile-style arguments, but it does not implement every original libfile operation.

Reads a StrongHelp manual container and either lists the files it contains or extracts them into a host-side source tree. Extracted files keep RISC OS filetype suffixes where relevant.

If --extract-dir is omitted, the current directory is used for extraction.

For the underlying manual format, see ../appendix/stronghelp-file-format.

Packages a directory tree into a StrongHelp manual file. If no input directory is supplied, the current directory is used. If -o is omitted, the output file defaults to Manual.

The command is intended for rebuilding an extracted or hand-maintained StrongHelp source tree rather than editing a manual directly.

For non-RISC OS use, note these implementation caveats: generated files receive a datestamp of 1/1/1900, and the implementation assumes little-endian layout plus the expected structure packing.