== Packages ==

Once a set of writing system components have been created, we need to package them for distribution. Smith works to make that as simple but as powerful as appropriate. There is an optional `package` attribute. If this attribute is set, it is set to a package object corresponding to which package the component should be added to. In addition, a global package object is created into which go all the components for which no `package` attribute has been set.

The global package can take its parameters from the wscript file as global variables with the same name as the attribute, but with the name uppercased.

The attributes to package are:

appname::
    Base application name to use for the installer in lower case. This is required.

version::
    Version number of the installer. This is required.

desc_short::
    One line description of the package.

docdir::
    Directory tree to walk pulling in all the files as source files. Used for identifying documentation files that you want to include in a zip/tarball/release. It can also be used to add documentation files to supplementary fonts built from the same repository. If your wscript produces multiple packages with WOFF files, you need to use a special technique to get the WOFF files to appear in the appropriate web folders in each package. Otherwise you may end up with all the WOFFs from both font families appearing in both packages. There are two steps to setting this up:

    - Adjust the woff() command in the wscript supplemental package designspace routine to place the WOFFs in a temporary folder when built. You also need to add `dontship=True` so that the contents of the temporary folder don’t get duplicated.

[source,python,linenums]
----
    woff = woff('web_book/${DS:FILENAME_BASE}.woff',
    metadata=f'../source/familybook-WOFF-metadata.xml', dontship=True)
----

    - Set the docdir in the package definition to map the temporary folder to the normal web folder. Example:

[source,python,linenums]
----
    bookpackage = package(appname = "FamilyBook",
        docdir = {"documentation": "documentation", "web_book": "web"})
----

Those steps will place the appropriate WOFF fonts in the package web folders.

However if you want the CSS and HTML docs from the repo `web` folder to appear you need to: 

- Create a permanent `web_book` folder in the project root
- Copy the CSS and HTML docs from web into `web_book`
- Modify those files to use the supplemental family names


You can also use docdir to use an alternative folder in the project as the source for the “documentation” folder in the supplemental package. For example, if you want your “Book” family to instead include documentation from a separate `documentation_book`, you could do this:
[source,python,linenums]
----
    bookpackage = package(appname = "FamilyBook",
        docdir = {"documentation_book": "documentation", "web_book": "web"})
----

package_files::
    This is a dictionary of filename globs as keys, including the use of ** for recursion. The values are replacement paths. If the value path ends in \/ the path from the key, up to the first *, is replaced with this value.

zipfile::
    Name of zip file to use when creating smith zip. Is auto-generated if not set, based on appname and version.

zipdir::
    Directory to store generated zip file in, relative to build directory.

readme::
    Name of readme file to include in the package (default `README.txt`)

buildversion::
    This is often defaulted. For a release build (-r or smith release) it is set to empty. For a non-release build, the core of buildversion is based on the current VCS commit identifier. For git this is the sha. The specification of its format is in `buildformat`. `buildversion` is a combination of `buildlabel` plus the generated identifier based on `buildformat`. The buildversion is included in the generated names of the zip and tarball targets and the font version (if the font version attribute is not a tuple).

buildlabel::
    The development version label, for example alpha2.

buildformat::
    Formats the vcs commit identifier or whatever in the development buildversion. This is a str.format type string and the following named parameters are available. The default for this variable is `dev-{vcssha:6}{vcsmodified}`

    vcssha;;
        Unique commit identifier

    vcsmodifier;;
        Returns M if the sources we are building from are not the same as the commit.

    vcstype;;
        Specifies the VCS system being used: git, hg, svn.

    buildnumber;;
        Continuous integration build build number

=== Functions ===

==== getufoinfo ====

This function takes a path to a UFO font. It extracts information from the font and sets the corresponding variables in the wscript as if they had been entered directly. Thus those variables are usable elsewhere in the wscript. Important note: `getufoinfo()` must be the first function called in the wscript.

The variables set are:

version::
    Taken from the VersionMajor and VersionMinor

buildlabel::
    Taken from the openTypeNameVersion parsed to remove the initial Version d.ddd and any dev-ident.
