Please note that Sincerity is still under development and that this documentation is incomplete.
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.
- 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.
- [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.
- --force: With this switch, even if the directory already exists, the command would still copy the template into it. Note that this might overwrite existing files.
container:use
Changes the current container to which Sincerity is pointing.
- 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.
- 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.
- --force: With this switch, even if the target directory already exists, the command would still copy the files into it. Note that this might overwrite existing files.
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.
- 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.
- Name: The repository name must be unique per its section.
- 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:
Will expand to:
If the following entry is in "shortcuts.conf":
sincerity attach maven-central
sincerity attach public maven-central maven http://repo1.maven.org/maven2/
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.
- Section: See the "repositories:attach" command.
- 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.
- --verbose: By default only the name of the license will be printed. With this switch, the URL will be printed, too, if available.
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.
- 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.
- 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".
- [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.
- --only: Ignores all implicit dependencies of this dependency
- --force: Forces the specified version, even if a different version is preferred by a different dependency
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:
Will expand to:
If the following entry is in "shortcuts.conf":
sincerity add velocity 1.7
sincerity attach three-crickets : add org.apache.velocity velocity 1.7
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.
- 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.
- 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.
- --packages: Shows artifacts within packages (by default these are not shown).
- --verbose: In non-verbose mode (the default) only the type of artifact is shown. In verbose mode you'll see the complete relative path to the artifact as well as its size in bytes.
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:
- 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.
- 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/").
- Recursion: If your dependency has sub-dependencies, they are added. Phases 1 to 3 are repeated for each.
- 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.
- 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.
- 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.
- 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.
- --overwrite: This affects phase 6. See "packages:unpack" for more information.
- --verify: This affects phase 6. See "packages:unpack" for more information.
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.
Also see the "container:clean" 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".
- [Filter]: Currently unused.
- --overwrite: By default the command will not overwrite existing files, unless these files were previously installed by Sincerity and have not been modified since. This behavior ensures that you do not lose your custom work. However, you can override this behavior using this switch. Be careful: this will overwrite files unpacked by all packages. If you only want to overwrite a select few files, it is best to delete them and then run "unpack" without this switch.
- --verify: Verifies that artifacts have been unpacked correctly. Slower but safer.
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.
- 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.
- 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.
- 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.
- --background: By default this command will block until the child process exits. However, using this switch Sincerity will not block and continue processing its command chain. Note that this would not stop the child process from ending when the Sincerity parent process ends.
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.
- 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.
- --script=: If present, the console will load this script file, run it one line at a time, and then exit. Empty lines and lines beginning with a "#" (comments) will be ignored. In the script, you may separate commands via ":" or a newline, with the same final effect.
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.
- --ui=: Let's you change the Swing look-and-feel. Look-and-feels supported on most JVMs are: "metal" and "nimbus". Note that if no look-and-feel is specified, or the specified look-and-feel is not found, then Sincerity will attempt to default to the native look-and-feel, unless the native platform is GTK. We found the GTK look-and-feel to be so riddled with bugs that we decided to spare you from it.
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.
- --script=: If present, the console will load this script file, run it all at once, and then exit. Note that you cannot use the ":" shortcut to run Sincerity commands here, because this file is pure JavaScript. However, you can run Sincerity commands using sincerity.run(...) calls.
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.
- [Source directory]: Recursively compiles all ".java" files in this directory (relative to the container root). Defaults to "/libraries/java/".
- [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.
