Hosted by Three Crickets

Sincerity
Packaging and Bootstrapping
For the JVM

Please note that Sincerity is still under development and that this documentation is incomplete.

Sincerity logo: jackrabbit and flowers

Core Plugins

These are the plugins that come with the Sincerity installation and implement its most essential commands.
Since these commands are used so often, it's a good idea to avoid implementing these command names in your own custom plugins, so that there would never be ambiguity for the essentials. In other words, treat "add", "install", etc. as reserved command names.
We've organized them here in the order by which you'd likely use them.
Optional arguments are marked by square brackets.

Container

Manages Sincerity containers.

container:create

Creates a new container using a container template and points Sincerity to it, making it the new current container.
Arguments
  1. Container root directory: If the directory does not exist, this command will create a new container there. If the directory already exists and is a container, points Sincerity at it.
  2. [Template name]: This is the name of a subdirectory under your Sincerity installation's "/templates/" subdirectory. Will default to "default". Sincerity will recursively copy the files from the template into your new container. Use the "templates:templates" command to see available templates.
Switches

container:use

Changes the current container to which Sincerity is pointing.
Arguments
  1. Container root directory: The path must point to a valid container root, meaning that it must have a "/.sincerity/" subdirectory.

container:clone

Creates a clone of the current container.
Arguments
  1. Target container root directory: If the directory does not exist, this command will create a new container there, recursively copying all files from the current container to it. Note that Sincerity will not switch to the new container: use the "container:use" command if you need to do that.
Switches

container:clean

This command is the same as "artifacts:uninstall" but also deletes the "/cache/" subdirectory.

Repositories

Manages repositories within the current container. Adds a "Repositories" tab to the Sincerity GUI.
The "artifacts:install" command searches for dependencies in all attached repositories, in order.
Instead of using these commands, you can also edit the container's "/configuration/sincerity/repositories.conf" file directly. See the Ivy documentation for resolvers.

repositories:repositories

List all repositories attached to the current container in order by section.

repositories:attach

Attaches (adds) a repository to the current container. This command modifies the "/configuration/sincerity/repositories.conf" file.
Arguments
  1. Section: Repositories are searched in the order they are added, but are first ordered by section. By default Sincerity containers have two sections: "private" and then "public", in that order. Thus, any repositories you attach to the "private" section will be searched before any repositories attached in the "public" section.
  2. Name: The repository name must be unique per its section.
  3. Type: Sincerity currently supports two types of repositories: "maven" (you can also use the "ibiblio" alias) and "pypi" (you can also use the "python" alias).
Arguments after the first three depend on the type of repository attached. However, both currently supported types require one additional argument: the repository base URL.
Note that this command supports implicit shortcuts that begin with the "attach#" prefix. For example:
sincerity attach maven-central
Will expand to:
sincerity attach public maven-central maven http://repo1.maven.org/maven2/
If the following entry is in "shortcuts.conf":
attach#maven-central = attach public maven-central maven http://repo1.maven.org/maven2/
To see all available "attach#" shortcuts in your container use the "shortcuts:shortcuts" command.

repositories:detach

Detaches (removes) a repository from the current container. This command modifies the "/configuration/sincerity/repositories.conf" file.
Arguments
  1. Section: See the "repositories:attach" command.
  2. Name: See the "repositories:attach" command.

Dependencies

Manages dependencies for the current container. Adds "Dependencies" and "Licenses" tabs to the Sincerity GUI.
Instead of using these commands, you can also edit the container's "/configuration/sincerity/dependencies.conf" file directly. See the Ivy documentation for dependencies.

dependencies:dependencies

Lists all dependencies in the current container as a tree structure. Dependencies that are not installed will be listed in parentheses.
For a large dependency tree, it may be easier to use the Sincerity GUI instead of this command.

dependencies:licenses

Lists all licenses per all dependencies in the current container. Note that dependencies may be available via more than one license.
Please be aware that you should not treat the output of this command as legal advice. Package maintainers do their best to provide you with correct and useful information, but you should yourself investigate the licensing available per each library you use to avoid breaking the law.
Switches

dependencies:add

Adds a dependency to the current container. Note that this does not download artifacts: all it does is modify the "/configuration/sincerity/dependencies.conf" file.
The reason this command doesn't install files is that installation requires a resolution phase that goes over all dependencies and their sub-dependencies and selected the highest possible versions of dependencies. Use "artifacts:install" to download and install artifacts. It will also delete artifacts no longer used in the revised dependency tree.
Arguments
  1. Group: The dependency group name. This is sometimes also called an "organization," though it may be a bit misleading, because a group can refer to a set of products within an organization. Group names tend to follow the Java package naming format. For example, Prudence's group name is "com.threecrickets.prudence". Unfortunately, group names are not standardized and many projects follow their own conventions.
  2. Name: This is the name of the dependency within the group. It is usually a simple string, possibly with dashes, the project. For example, the name for the "Prudence Example" application within the Prudence group is "prudence-example".
  3. [Version]: If you do not specify a specific version (or use the special "latest" string), Sincerity will resolve for the highest available version. Sincerity supports range specifications for versions. For example. "[1.0,2.0[" will match versions that are greater than or equal to 1.0 but lesser than 2.0.
Switches
Important: Sincerity uses Ivy's dynamic revision format for versions, which look similar to Maven's but is in fact interpreted quite differently. This is a cause for many mistakes in using version constraints in Sincerity!
Note that this command supports implicit shortcuts that begin with the "add#" prefix. For example:
sincerity add velocity 1.7
Will expand to:
sincerity attach three-crickets : add org.apache.velocity velocity 1.7
If the following entry is in "shortcuts.conf":
add#velocity = attach three-crickets : add com.org.apache.velocity velocity
To see all available "add#" shortcuts in your container use the "shortcuts:shortcuts" command.

dependencies:revise

Allows you to change the version of a previously added dependency. The format is identical to "dependencies:add": the difference is that a new dependency cannot be added with this command, only revised. For example:
sincerity add org.apache.velocity velocity 1.7
sincerity revise org.apache.velocity velocity latest

dependencies:remove

Removes a dependency from the current container. Note that this does not delete installed artifacts: all it does is modify the "/configuration/sincerity/dependencies.conf" file.
Use "artifacts:install" or "artifacts:prune" to delete artifacts no longer used in the revised dependency tree, or "artifacts:uninstall" to delete all artifacts.
Arguments
  1. Group: The dependency group name. This is sometimes also called an "organization," though it may be a bit misleading, because a group can refer to a set of products within an organization. Group names tend to follow the Java package naming format. For example, Prudence's group name is "com.threecrickets.prudence". Unfortunately, group names are not standardized and many projects follow their own conventions.
  2. Name: This is the name of the dependency within the group. It is usually a simple string, possibly with dashes, the project. For example, the name for the "Prudence Example" application within the Prudence group is "prudence-example".
For example:
sincerity add org.apache.velocity velocity 1.7
sincerity remove org.apache.velocity velocity

dependencies:exclude

Forcibly excludes an implicit dependency from being downloaded. The format is identical to "dependencies:remove". For example:
sincerity exclude org.apache.velocity velocity

dependencies:override

Overrides the version of an implicit dependency. Note that this does not actually add the dependency. If the dependency is not in the tree, then the override has no effect. The format is identical to "dependencies:add":
sincerity override org.apache.velocity velocity 1.6

dependencies:freeze

Overrides the versions of all explicit and implicit dependencies to be their currently installed versions. This ensure that future runs of "artifacts:install" will result in exactly the same version installations.

dependencies:reset

Removes all dependencies from the current container. Note that this does not delete installed artifacts: all it does is empty the "/configuration/sincerity/dependencies.conf" file. Use "artifacts:uninstall" to delete installed files.

Artifacts

Manages artifacts in the current container. Adds an "Artifacts" tab to the Sincerity GUI.

artifacts:artifacts

Lists artifacts available for each dependency of the current container. If the dependency is not installed, it will be listed in parentheses.
Switches

artifacts:install

This powerful command downloads and installs artifacts belonging to the current container's dependencies and their sub-dependencies from the online repositories to which the container is attached. It should thus be used after "dependencies:add" and "repositories:attach" have been used. This command also handles upgrades and resolves dependency version conflicts.
Installation happens in seven phases:
  1. Checking: First, it searches for your dependencies in all attached repositories in order. It uses the "/configuration/sincerity/dependencies.conf" and "/configuration/sincerity/repositories.conf" files as a starting point. Though you can edit these directly (or copy them from elsewhere), you may prefer to use the "dependencies:add" and "repositories:attach" commands to manipulate them instead.
  2. Meta-data: When found, the meta-data (in Maven this is a .pom file) for the package is downloaded and stored in a local cache (under "/cache/sincerity/packages/").
  3. Recursion: If your dependency has sub-dependencies, they are added. Phases 1 to 3 are repeated for each.
  4. Resolution: Now that we have a complete dependency tree, it will be "resolved." This means that duplicate dependencies will be skipped and highest possible versions for dependencies will be selected. Note that upgrades are handled by this phase: if a newer version of a certain dependency is found, it will be selected instead of the previously installed one. Rarely, this phase may fail with an error due to version conflicts that cannot be resolved.
  5. Download/Delete: The dependencies selected for installation in the resolution phase will be downloaded, and those that were previously installed and are no longer needed (for an upgrade) will be deleted. You can use the "dependencies:dependencies" command to see the whole dependency tree, including dependencies that were selected to not be installed by the resolution phase. A more detailed report will be made available in "/cache/sincerity/resolution/threecrickets-sincerity-container-default.xml". Note that this XML report uses XSL and CSS to make it nicely readable in a web browser.
  6. Unpack: Installed packages will be unpacked. This is identical to the "packages:unpack" command, and may cause new artifacts to appear in your container, as well as arbitrary code to be executed via installer hooks in a package. It will not by default overwrite existing files.
  7. Prune: Unused artifacts will be deleted, unless you have changed them. This is identical to the "artifacts:prune" command.
Under the hood, Sincerity relies on Ivy to handle phases 1 to 5, and it may be useful to refer to its documentation if you require specialized configuration and handling.
Note that remote repositories introduce consider delay for phases 1, 2 and 5. Furthermore, the more repositories you attach, the longer phase 1 will take, as each repository is checked in sequence. For these reasons, as well as saving you from network/server failure by 3rd party providers, it is strongly recommend that you run a local proxy for the repositories you use. You can install one easily with Sincerity using the Nexus skeleton.
Switches

artifacts:uninstall

This command deletes all artifacts installed by "artifacts:install", unless these artifacts have been changed since they've been installed. This behavior ensures that you do not lose your custom work. If a package has an uninstaller hook, it will be executed after its artifacts are deleted.
This command is useful for leaving your container clean of any dependencies. Though the artifacts are deleted, they are still added to your container. Thus, this command is entirely reversible by issuing a "artifacts:install" command.

artifacts:prune

Deletes artifacts that were previously installed by "artifacts:install" but for which their dependencies no longer exist. Artifacts that were changed since installation will not be deleted. This behavior ensures that you do not lose your custom work.
You usually would not have to run this command by itself, because it is part of "artifacts:install". However, it may be useful in case you are manipulating the contents of "/libraries/jars/" manually.

Packages

Manages packages in the current container.

packages:unpack

Unpacks all Sincerity packages in "/libraries/jars/". If a package has an installer hook, it will be executed after its artifacts are unpacked.
You usually would not have to run this command by itself, because it is part of "artifacts:install". However, it may be useful in case you are manipulating the contents of "/libraries/jars/" manually.
It is also useful in case you've made various changes to unpacked artifacts and want to restore them to their initial unpacked state. A good way to do this is to delete all the files that you want to restore and then run "sincerity unpack".
Arguments
  1. [Filter]: Currently unused.
Switches

Delegate

Manages entry points into the current container, and is the primary means to run applications in it. Adds a "Programs" tab to the Sincerity GUI.

delegate:main

Calls the main() method within a JVM class. The class may exist anywhere within the current container, within the Sincerity installation, or elsewhere in the JVM classpath.
Arguments
  1. Classname: This is the fully qualified JVM class name. For example, "org.myapplication.Service". Note that the class has to have a method named "main" with the correct signature (public, returns void, with an array of strings as its only argument).
Additional command arguments after the first will be sent as arguments to the main() method.

delegate:start

Executes a Scripturian document.
Though Sincerity comes with support for JavaScript, documents can be written in any installed programming language that support Scripturian. The document extension will tell Scripturian which language engine to use: ".js" for JavaScript, ".py" for Python, ".rb" for Ruby, etc. Use the "delegate:languages" command to list all supported languages.
Your code will have full access to Sincerity's execution environment and API. See the chapter on Programming for more information.
Scripturian will store compiled code in the "/cache/" subdirectory, speeding up subsequent runs. For example, JavaScript classes will be stored under "/cache/javascript/". You can safely delete this files.
Arguments
  1. Document name: The argument is a document name, either beginning with a "/" and relative to the current container root, or a simple string specifying a filename in the "/programs/" subdirectory. Use the "delegate:programs" command to list all files under "/programs/". As usual with Scripturian, filename extensions should not be used. If the name points to a directory, then a file named "default" (with the appropriate programming language extension) in that directory will be executed. For example, "sincerity start /component/" would execute "/component/default.js" from within the current container, while "sincerity start component" would execute "/programs/component.js".
Additional command arguments after the first will be ignored by Sincerity, but will be forwarded to the program and can be accessed from within its code using the application.arguments API.

delegate:execute

This command starts a new process, which would be a child process of Sincerity. Standard output and input from the child process are piped to the current standard output and input.
This command is useful not only for integrating non-JVM code into Sincerity, but also for hashtag support, allowing you to incorporate dynamic language scripts, for Python, Ruby, etc. Since Sincerity controls the environment of the child process, it can guarantee that environment variables and other properties are set according to the current container.
Arguments
  1. Executable name: The argument is a filename relative to the current container's "/executables/" subdirectory. The file must be executable by the underlying operating system. On *nix this includes support for hashtag script files.
Switches

delegate:programs

Lists all available programs in the current container (documents in the "/programs/" subdirectory). Use the "delegate:start" command to start them.

delegate:languages

Lists all languages installed in the current container that support Scripturian.

Templates

Manages templates in the Sincerity installation. Adds a "Templates" tab to the Sincerity GUI.
Templates are used by the "container:create" command to initialize new containers.

templates:templates

Lists all templates available in the Sincerity installation.

templates:templatize

Turns the current container into a Sincerity template. This works by simply recursively copying the current container into your Sincerity installation's "/templates/" subdirectory. Note that you must have write permissions there in order for this to work.
Note that you can manipulate the "/templates/" subdirectory directly. This command is merely for convenience.
Arguments
  1. Template name: A new subdirectory to be created under your Sincerity installation's "/templates/" subdirectory. Note that this command will not copy over an existing template! If the directory already exists, you will get an error. You must manually delete the directory if you want to change an existing template using this command.

Shortcuts

Manages shortcuts for the current container. Adds a "Shortcuts" tab to the Sincerity GUI.
Your shortcuts are defined in your container's "/configuration/sincerity/shortcuts.conf" file.

shortcuts:shortcuts

Lists all available shortcuts in the current container.

Help

Provides general information about your Sincerity installation. Adds a "Commands" tab to the Sincerity GUI.

help:version

Lists Sincerity version information. This includes the numerical version and the build timestamp. An example of output:
built=Jun 18 2013, 15:28:46, TZ+0800
version=1.0-dev5 

help:help

Lists all available Sincerity commands (in full form) from all available Sincerity plugins. This includes both plugins installed in the current container and those available in the Sincerity installation.

help:verbosity

If no argument is provided, prints out the current Sincerity output verbosity. If an argument is provided (integer >=0) then changes the current verbosity. Note that the default verbosity is 1, and you can change the verbosity several times within a chained Sincerity command.
Verbosity is interpreted individually by individual commands, though 0 usually means "silent," 1 means "only important messages" and 2 means "quite chatty." Higher values usually include more minute debugging information.
Note that verbosity is only used to control messages to standard output and standard error. Configuring logging should be done separately, via the logging plugin.

Shell

User interfaces to Sincerity.

shell:console

A straightforward console in which you can run Sincerity commands. The console supports basic command completion using the TAB key and persistent command history using the UP and DOWN keys.
Use "exit" (or CTRL+C) to exit the console. Use "reset" to reset the command history. The history is available in the "/cache/shell/console.history" file.
See "jsshell:jsconsole" for a richer console, in which you can use full JavaScript code.
Switches

shell:gui

Starts the Sincerity Sincerity GUI. The GUI will go through all available plugins and try to call the optional gui() entry point if they have them, allowing plugins to enhance the GUI as is appropriate.
Note that this command blocks until the GUI is shut down.
Switches

JavaScript Shell

User interfaces to Sincerity using JavaScript.

jsshell:jsconsole

A JavaScript console in which you can run JavaScript code, with full access to all JavaScript and JVM libraries in the container. The console supports basic command completion using the TAB key and persistent command history using the UP and DOWN keys.
As a shortcut, any line beginning with a ":" will execute a Sincerity command, similar to using the basic "shell:console".
Use "exit" (or CTRL+C) to exit the console. Use "reset" to reset the command history. The history is available in the "/cache/jsshell/jsconsole.history" file.
Switches

Java

Support for the Java programming language.

java:compile

Compiles Java source files (".java") into JVM class files (".class") using the current container's classpath.
Note that you must have a full JDK to use this command: a JRE usually does not come with a Java compiler.
Arguments
  1. [Source directory]: Recursively compiles all ".java" files in this directory (relative to the container root). Defaults to "/libraries/java/".
  2. [Classes directory]: Output ".class" files here. Defaults to "/libraries/classes/". Note that Sincerity will always include this directory in its classpath, so it may be a good idea to keep this default.

The Sincerity Manual is provided for you under the terms of the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. The complete manual is available for download as a PDF.

Download manual as PDF Creative Commons License