What is a Project Archive File?
Project archive files are tar.gz or zip archives of a doxx project directory. These archives wrap all project build files under a single filename. doxx can build directly from a project archive file which simplifies the path settings in a user's local key file for large projects with complex directory structures. Project archives also permit distribution of binary files (e.g. image files, audio files, PDF files) in addition to the text files specified in project templates.
Project Archive Directory Structure
The required files in a project archive differ slightly from a non-archived project.
Project Archives Include:
project.yamlbuild spec file
- one or more template files
- any number of verbatim text files and/or binary files
- project-specific directory structure
key.yamlin a project archive.
- has the same structure as a key.yaml file
An archived project includes a key file that is named
pkey.yaml rather than
key.yaml. This is to avoid collisions with local user key files when an archive is unpacked into a local build directory. If
doxx pull is used to pull and unpack a remote archive file, the
pkey.yaml file is renamed
key.yaml if the file is not already present in the user's working directory. If the file is already present, it is assumed that the user wants to preserve their existing
key.yaml file and
pkey.yaml writes to the directory.
By default, builds always take place from
doxx build is used without an argument and there is no exception with unpacked project archives. If a user must build from the
pkey.yaml file, you must explicitly state this in your build instructions because it will not take place by default if they have generated their own
pkey.yaml build specification header sections can include any build specification field except
project: and employ the same build spec syntax as
key.yaml files. Please see the key file documentation for more details.
- defines the project build file paths
- is used when builds take place directly with the project archive file without previously unpacking it
- includes only the build specification head section of a standard key file
project.yaml file defines the local project template files to be used when a user builds directly from a project archive file without previously pulling and unpacking the entire project. The file includes the build specification header section of a standard doxx key file without a text replacement definition section.
Here's an example of a properly formatted
--- templates: [example.doxt, example2.doxt, example3.doxt] ---
Template files in project archives have the same standard format that is described in the Templates section of the documentation.
Project Archive File Distribution
Project archive builds:
- can be performed directly with local or remote project archive files (tar.gz or zip)
- can be performed after a user unpacks a project archive file
doxx supports builds from local or remote project archive files with the
doxx build command. Remote project archives must be accessible to doxx by GET request using the http:// or https:// protocol.
To build directly from a project archive file, the key file should include the
project: build spec field with either a local file path or a URL to the project archive file (see key file documentation). For this type of build, the user will be expected to generate a
key.yaml file in the build root directory. They can either make this file themselves or one can be distributed to them outside of the project archive file. The user executes
doxx build with
key.yaml in the root of the new project directory to initiate the project build from the archive file.
It is also possible to unpack a project archive prior to the build. doxx provides the
doxx pull command which pulls remote archive files to the local machine and unpacks them in the current working directory. There is also cross-platform (including Windows) support for local tar.gz and .zip archive decompression and unpacking with the
doxx unpack command if project users obtain the archive file in a different way (e.g. browser download). With this form of project distribution, the key file should specify local template files with either the
templates: build spec field rather defining a project archive file with the
project: field. The benefits of this approach are that the user can examine the contents of the project prior to the build and a key file stub can be packaged in the archive for use in the build. The user completes the key file and uses
doxx build to initiate the build from the unpacked project files.
doxx pack (docs) can be used to create tar.gz or zip archives of your project.
doxx unpack (docs) can be used to unpack tar.gz or zip archive files.
doxx pull (docs) pulls a remote project archive file and unpacks it in the current working directory.