Smackspec

A smackspec is a series of lines beginning with a description section that gives general information about a package and which is followed by zero or more platform sections that give properties of how to build the package on a platform (a platform could be an SML compiler or the combination of an SML compiler and operating system).

For the initial version of Smackage, the only pieces of smakcspecs that the program usefully interprets are "requires" specifications (one exception is versions.smackspec files, for which smackage also interprets the "protocol" and "requires" sections.) In particular, the platform sections and the included "build" and "install" sections are intended primarily as documentation for users.

First section

• bug-url: <uri> (only one) - Where bug reports can be filed on the Internet (can also be an email address).
• comment: ... (multiple) - Comments (a single comment can span multiple lines, each of which begins with comment:).
• description: ... (only one) - A one-line description of the project.
• documentation-url: <uri> (only one) - Where documentation can be found on the Internet.
• license: ... (multiple) - What license (or licenses) the project is released under. If multiple licenses appear, that means that the project can be cross-licensed under any of the mentioned license, it does not mean that the project must be licensed under the combined requirements of the multiple licenses.
• keywords: ... (only one) - Keywords, comma-separated.
• maintainer: ... (multiple) - Contact information for maintainer(s).
• provides: <package> <version> (only one) - Which name and version is provided by this package; <version> is a full semantic version, either vMajor.Minor.Patch or Major.Minor.Patch. NOTE - it would be nice to make 'version' option, if I'm publishing something, the tag already tells me what version it is... - rjs
• remote: <protocol> <uri> (only one) - Where this package can be obtained on the internet; at this point only the git protocol is supported.
• requires: <package_name> <constraint> (multiple) - What dependencies the package has; <constraint> can be of the form v1, v1.3, or v1.4.6 (the v is optional). If foo v1.3 is required, then it would be appropriate for the package to point to files from the required foo package as $(SMACKAGE)/foo/v1 or $(SMACKAGE)/foo/v1.3, but it would be inappropriate for the package to point to files from the required foo package as $(SMACKAGE)/foo/v1.3.4 - to do that, version foo v1.3.4 should be required. It is suggested that dependencies should only be on major versions, if possible, as Semantic Versioning requires backwards compatibility within a major version.
• upstream-url: <uri> (only one) - A link to where this package came from before it was in the Smackage system.
• upstream-version: ... (only one) - Smackage packages MUST use semantic versioning, which may not mesh with existing versioning schemes. These "official" versions can be recorded here.

Platform sections

Platform sections begin with a line platform: <platform>, where <platform> is either *, <compiler> or <os>+<compiler>. The * value indicates that this platform section is appropriate for any os/compiler combination.

Supported values of <compiler>:

• mlton
• polyml
• smlnj

Supported values of <os>:

• win
• linux
• osx

The following tags go inside of a platform section:

• build: <commandline> - A command line that, run in the package foo's directory, builds the project. This is optional; only the install command is required to support installation of a package. As a convention, it should put the executables in the root directory of the project; this will support an eventual smack build command which will look for a projectname.smackage file in the current directory.
• comment: ... - Comments can appear anywhere.
• documentation: ... - Builds documentation. Not sure what this means yet, really.
• install: <commandline> - a command line that, when run after the build commandline (if any), will put the created executable at ../../../bin
• test: <commandline> - a command line that, run in the package's directory, tests that directory (TODO: specify this better)

All of these targets are optional. For example, you might want to install something, but you don't need to build it. This would be achieved by constructing an appropriate platform section containing only an 'install' command.

Examples

The following is a file that provides the minmum information necessary to obtain a project; this is the information that smack refresh automatically generates by querying git repositories.

provides: cheese v1.0.0
remote: git git://github.com/bovik/cheese.git

provides: cheese v1.0.0
remote: git git://github.com/bovik/cheese.git

The following is a slightly informative file that could go in the root of the cheese project as cheese.smackspec. It is not required that .smackspec files include provides and remote information.

description: Need some cheese? We'll give you some cheese
maintainer: Harry Bovik <[email protected]>
comment: This is a
comment: multi-line comment
comment: about the project
requires: dec-5 v201