tcl-quill 0.3.0: Quill Project Automation System for Tcl/Tk

project(5): Quill Project File Syntax

SYNOPSIS
DESCRIPTION
STATEMENTS
AUTHOR

SYNOPSIS

project project version description
homepage url
app name ?options...?
provide name
require package version ?-local?
dist name patterns

DESCRIPTION

The Quill project file, project.quill, describes a Tcl project, its build targets, and its dependencies, and thereby allows Quill to work its magic. This man page documents the statements that can appear in project.quill.

The project.quill file is usually created automatically by Quill via the "quill new" command, and several statements can be added by the "quill add" command. Other changes can be made by the user.

A typical project.quill file consists of:

STATEMENTS

The following statements may appear in project.quill.

project project version description
Required. This statement must appear in every project.quill file, and should be the first statement in the file. The project should be the name of the project; often it will be the name of the project at a site like GitHub. It may contain letters, digits, underscores, and hyphens.

The version is the version of the project; it will also be used as the version number for any library packages exported by the project. It must take a form acceptable to Tcl's package provide command.

The description is a brief one-line description of the project. It is included in generated documentation. It may not be the empty string.

homepage url
Sets the URL of the project's home page. This URL is included in generated project documentation.

app name ?options...?
States that the project contains an application called name. A project may define multiple applications; the first to appear in the project file is called the primary application.

The name may contain letters, digits, underscores, and hyphens.

Every application will have a loader script "root/bin/name.tcl", and will probably have an associated Tcl package, nameapp, whose code is found in "root/lib/nameapp/". The application can be executed in development via the "quill run" command, or by executing the loader script directly.

By default, the application will be built as a console-oriented kit. The following options may be used to customize how the application is built:

-gui
If the -gui option is specified, the application is a GUI application and the Tk package will be required automatically. When built as a starpack, a Tk basekit will be used.

-exetype kit | exe
Exe type kit results in a "starkit", which can be run against any compatible tclsh. If the project requires only pure-tcl external libraries, the "starkit" may be usable on any platform.

Exe type exe results in a "starpack", a genuine stand-alone executable, for the current platform, whatever it is.

Quill is capable of building cross-platform, i.e., it can build Linux executables on Windows and Windows executables on OS X. See the help for the quill build command.

The default application type is kit.

provide name
States that the project exports a Tcl library package called name, whose code is found in the directory root/lib/name. A project may export any number of library packages.

The name may contain letters, digits, underscores, and hyphens.

require package version ?-local?
States that the project has an external dependency upon the given version of the named package. The package and version should be stated in the same form as you would give to Tcl's package require command.

Given this information, Quill will:

Note that Quill does not automatically package require the packages into Tcl; a project may contain multiple applications and exported library packags, and each may have slightly different dependency requirements. Instead, the user adds the relevant package require statements to each build target's pkgModules.tcl file, and Quill will then endeavor to keep the version numbers up to date.

If the -local option is included, then Quill assumes the dependency is a locally-developed package, and will not attempt to retrieve it from ActiveState's teapot repository.

dist name patterns
Defines a distribution with the given name and file patterns. The quill dist command will produce a distribution .zip file for each named distribution; the file will be called

project-version-name.zip

If the name includes the string "%platform", the string will be replaced by the current platform name, as returned by platform::identify. Since "exe" executable files also include the platform::identify string, this allows one distribution set to support installation on most or all platforms.

The contents of the file is determined by the patterns, which is a list of glob-patterns relative to the project's root directory. For example, the following distribution includes the application, the README file, and the .html files in the docs/ folder:

dist install {
    %apps
    bin/myapp.kit
    README.md
    docs/*.html
}
The list of patterns can also include the special pattern %apps, which pulls in all application files for the platform, and %libs, which adds in the teapot .zip files for each of the library packages provided by the project. These files can be added directly into a local teapot using the teacup install command.

AUTHOR

Will Duquette.


Generated from project.manpage on Sat Nov 08 09:29:58 PST 2014