Please note that Sincerity is still under development and that this documentation is incomplete.
Language Plugins
These plugins add a language engine to your container. In some cases, this also means support for standard tools that come with the language distribution, such as a CLI, a REPL, and tools for compilation and packaging.
Most of these language engines support the Scripturian standard, meaning that with a language plugin installed you can:
- Write Scripturian programs and Sincerity programs in this language. For example, with Python installed, you can write a "/programs/fish.py" program and start it via "sincerity start fish". Note that the service plugin can also be used to run programs as daemons or services.
- Write Sincerity plugins in this language. For example, with Ruby installed, you can write a "/libraries/scripturian/plugins/fish.rb" plugin.
The "delegate:languages" command will list all Scripturian-supported languages in the container.
JavaScript Plugin
Though JavaScript was originally designed to be run in web browsers, it is a powerful general-purpose C-syntax language with Scheme-like closures that supports many programming paradigms, and has proved useful and popular outside the browser. Sincerity runs JavaScript code via either Nashorn (available from JVM 8) or Rhino.
Note: You do not need this plugin to install JavaScript support in a Sincerity container. All it does is provide you with a new command to get easy access to a JavaScript shell.
To install:
sincerity add javascript : install
To start a shell:
sincerity javascript
Fleshing Out
The shell can run script files and also evaluate inline scripts as arguments. Use "sincerity javascript -h" to see the command's possible arguments. An example of an inline script:
sincerity create mycontainer : add javascript : install : javascript -e "print('Hello, world')"
Note that this "javascript" does not use Scripturian, nor does it have access to any Sincerity APIs. To run JavaScript files in Sincerity's Scripturian environment use the "delegate:start" command.
Python Plugin
Python is a general-purpose multi-paradigm dynamic language with an exceptionally clean syntax and a rich ecosystem. Sincerity implements Python via Jython, and also has limited support for Jepp.
To install:
sincerity add python : install
To start a shell:
sincerity python
Ruby note: Due to conflicts in their implementations, you cannot currently use the Python and Ruby plugins in the same container.
Fleshing Out
The shell can run script files and also evaluate inline scripts as arguments. Use "sincerity python -h" to see the command's possible arguments. An example of an inline script:
sincerity create mycontainer : add python : install : python -c "print 'Hello, world'"
Note that this "python" command does not use Scripturian, nor does it have access to any Sincerity APIs. To run Python files in Sincerity's Scripturian environment use the "delegate:start" command.
Python has a very extensive ecosystem hosted on PyPI (a.k.a. "The Cheese Factory") in "egg" format. You can install libraries, frameworks and applications into your Sincerity container using a special version of "easy_install" included in this plugin as a Sincerity command. For example, let's install Beej's Flickr API:
sincerity easy_install flickrapi
Eggs will be installed into your container under the "/libraries/python/Lib/site-packages/" subdirectory.
Note that not all software written for CPython runs well on the Jython engine. See the software's documentation for more details.
The Sincerity Python plugin also include a "python" command (under "/executables/python") to allow for proper integration with Python software that starts Python subprocesses. You can run this command directly, and even use it with a shebang for executable files. For example, this file is executable:
#!/path/to/mycontainer/executables/python print 'hello world'
You can also place such files in your "/executables/" subdirectory and run them using Sincerity's "delegate:execute" command.
Ruby Plugin
Ruby is a general-purpose multi-paradigm dynamic language with a exceptionally full set of features and a rich ecosystem.
Sincerity implements Ruby via JRuby, an exceptionally robust implementation.
To install:
sincerity add ruby : install
To start a shell:
sincerity ruby
Python note: Due to conflicts in their implementations, you cannot currently use the Python and Ruby plugins in the same container.
Fleshing Out
The shell can run script files and also evaluate inline scripts as arguments. Use "sincerity ruby -h" to see the command's possible arguments. An example of an inline script:
sincerity create mycontainer : add ruby : install : ruby -e "puts 'Hello, world'"
Note that this "ruby" command does not use Scripturian, nor does it have access to any Sincerity APIs. To run Ruby files in Sincerity's Scripturian environment use the "delegate:start" command.
Ruby has a very extensive ecosystem hosted on RubyGems in "gem" format. You can install libraries, frameworks and applications into your Sincerity container using a version of "gem" included in this plugin as a Sincerity command. For example, let's install Flickraw, an API for accessing Flickr:
sincerity gem install flickraw
Gems will be installed into your container under the "/libraries/ruby/lib/ruby/gems/shared/" subdirectory.
Note that not all software written for Ruby runs well on the JRuby engine (though in some cases it may actually run better in JRuby). See the software's documentation for more details.
Other standard Ruby commands supported by the plugin are: "ast", "irb", "rake", "rdoc", "ri" and "testrb".
The Sincerity Ruby plugin makes sure that the execution environment will work with the JRuby ecosystem. Specifically, JRuby executable files start with the "env" shebang, for example:
#!/usr/bin/env jruby puts 'Hello, world'
You can place such files in your "/executables/" subdirectory and run them using Sincerity's "delegate:execute" command.
PHP Plugin
Though PHP was designed for generating web pages, it is also useful as a general-purpose templating language. Sincerity implements PHP via Quercus. Note that the free version of Quercus is included, but you may easily swap it for a purchased professional release if you have it.
To install:
sincerity add php : install
To start a shell:
sincerity php
Fleshing Out
The shell can run script files provided as arguments. Use "sincerity php -h" for more information. For example, let's create a file named "test.php":
<?php print "Hello, World!\n"; ?>
And then run it like so:
sincerity create mycontainer : add php : install : php test.php
Note that this "php" command does not use Scripturian, nor does it have access to any Sincerity APIs. To run PHP files in Sincerity's Scripturian environment use the "delegate:start" command.
PHP has a very extensive ecosystem hosted on PEAR, often in PHP archive (.phar) format. Though Sincerity does not yet support PEAR directly, you can install PEAR libraries using standard PHP and then copy them over to your Sincerity container.
Lua Plugin
Lua is an especially lightweight multi-paradigm dynamic language, which shares many features with JavaScript, but is nevertheless simpler to implement due to its minimalist design. The simple implementation allows for a register- rather than stack-based virtual machine and famously fast performance. Sincerity implements Lua via Luaj, which outperforms even the standard Lua in many situations and allows integration with JVM libraries.
To install:
sincerity add lua : install
To start a shell:
sincerity lua
Fleshing Out
The shell can execute Lua files provides as arguments, and also evaluate inline scripts as arguments. Use "sincerity lua -h" to see the command's possible arguments. An example of an inline script:
sincerity create mycontainer : add lua : install : lua -e "print 'Hello, world'"
Note that this "lua" command does not use Scripturian, nor does it have access to any Sincerity APIs. To run Lua files in Sincerity's Scripturian environment use the "delegate:start" command.
Additionally, the plugin supports a "luac" command to compile Lua source files into portable Lua bytecode, and a "luajc" command to compile into JVM classes.
Groovy Plugin
Groovy is a dynamic language with a syntax familiar to Java programmers, but with features inspired by Python, Ruby and Smalltalk. It provides exceptionally good integration with libraries written in Java, such that any JVM library is immediately also a Groovy library.
To install:
sincerity add groovy : install
To start shell:
sincerity groovy
Note that the Groovy plugin requires at least JVM 7 by default, because it depends on the invokedynamic version of Groovy. If you need to run on JVM 6, you can switch to the non-invokedynamic version with the following command:
sincerity exclude org.codehaus.groovy groovy-indy : add org.codehaus.groovy groovy : install
Fleshing Out
The shell can run script files and also evaluate inline scripts as arguments. Use "sincerity groovy" to see the command's possible arguments. An example of an inline script:
sincerity create mycontainer : add groovy : install : groovy -e "println 'Hello, world'"
Note that this "groovy" command does not use Scripturian, nor does it have access to any Sincerity APIs. To run Groovy files in Sincerity's Scripturian environment use the "delegate:start" command.
Clojure Plugin
Clojure is a modern Lisp designed for concurrency and performance. It is a superbly expressive language that supports robust functional programming as well as other paradigms.
To install:
sincerity add clojure : install
To start a REPL:
sincerity clojure
Fleshing Out
The REPL can run script files and also evaluate inline scripts as arguments. Use "sincerity clojure -h" to see the command's possible arguments. An example of an inline script:
sincerity create mycontainer : add clojure : install : clojure -e '(println "Hello, World")'
Note that the REPL does not use Scripturian, nor does it have access to any Sincerity APIs. To run Clojure files in Sincerity's Scripturian environment use the "delegate:start" command.
Clojure has a very extensive ecosystem hosted on Clojars. It is a standard Maven-type repository that is naturally supported by Sincerity, and attached by default if you use the "add clojure" shortcut. For example, let's install the flickr-clj, an API to access Flickr:
sincerity add clojure : add org.clojars.stanistan flickr-clj : install
A shortcut is also available for attaching Clojars explicitly:
sincerity attach clojars : attach maven-central
Note that many Clojars libraries also rely on Maven Central, so it's a good idea to attach it as well. Both are attached when you use the "add clojure" shortcut.
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.