Package definition file

Package definition file

The definition of a package for Fig can be done using a file (by default "package.fig" or "application.fig") with a simple language. Comments consist of an octothorpe ("#") through end of line.

At the top level of a file, you can put a grammar statement, asset or retrieve statements and config blocks. At this level, order of statements is not significant, with the exception of the grammar statement which, if present, must be the first one.

You need to have at least one config block for the package to be useable. The simplest file that could be referenced by anything else would look like

config default
end

A config block can contain environment variable, include, override, and command statements. Order of statements within config blocks is significant, with the exception of override and command statements, which can appear anywhere in a block, in any order.

A simple (nonsensical) example definition file that contains one of each kind of statement:

grammar v1

archive path/somefile.tar.gz
resource foo/*.jar

retrieve LOCATION_VARIABLE->"some relative directory path/[package]"

config default
    set VARIABLE=value
    add CLASSPATH='foo.jar'

    include dependency/1.2.3
    override indirect-dependency/4.5.6

    command
        echo 'Hello,' "world!"
    end
end

Note that Fig doesn't care about newlines (other than for comments), just whitespace. You could take the above file and replace the newlines with space characters and Fig would treat it just the same.

For more details see the v0, v1, and v2 grammars, and individual statement descriptions.

Package contents

You tell Fig what to include in your package using asset statements (resource and archive). The primary difference between the two is that the contents of the files referenced by archive statements are extracted upon installation. Thus, given a package.fig or application.fig file containing the statements

archive  path/somefile.tar.gz
resource foo/*.jar

the bundled up package will contain all of the jar files in the foo/ subdirectory of the current directory and the somefile.tar.gz archive. When package is installed, the jar files will be in a foo subdirectory of the package directory and the somefile.tar.gz contents will be extracted.

If multiple archives contain the same file, one version will end up overwriting the other. There are no guarantees as to which version of a file will be the last one written.

Caveat

In the current repository format, archives in a package are stored in a single flat directory. This means that if the last component of the path for an archive statement or a URL for a resource statement are not unique, you will run into problems. In a definition file containing:

archive  a-path/somefile.tar.gz
archive  another-path/somefile.tar.gz
archive  http://example/some/path/somefile.tar.gz
resource ftp://whatever/foo/bar/somefile.tar.gz

all of the files would end up clobbering each other. Fig does check for this situation and will prevent publishing such a package, but it's something you need to look out for. Note that same-named local resources with different paths are fine:

resource something/somefile.tgz
resource wherever/somefile.tgz

Declaring dependencies

You declare dependencies using include and include-file statements. You use override statements to affect your dependencies' dependencies.

Specifying runtime environment

You declare the environment via environment variable and retrieve statements.

Default commands

If a command to run is not given on the fig command-line, the command in a command statement is executed.

Where to put the contents of a depended upon package

If you need to get the contents of a package to a location outside of the repository, you use a retrieve statement.