SAM is an advanced compiler development framework and a set of compiler and software processing tools and technologies, produced by Job and Esther Technologies as part of the Eqela family of products and services.
SAM CE is a freely downloadable version of the compiler, which also serves as the reference implementation for the Sling programming language. SAM CE can be used to compile Sling programs to various target platforms, including HTML5, Android, iOS and .NET (including Mono and Microsoft .NET Framework). For the remainder of this article, we assume the use of SAM CE.
To download a copy of the compiler, please visit the Eqela website below:
SAM is distributed as a ZIP archive that is versioned using incremental release numbering, eg. "sam-r160", "sam-r161", etc. The higher the release number, the newer the compiler version. The actual compiler is distributed as a CLR managed-code executable file compiled for the .NET Framework, which can be executed on Windows as is, or using Mono on Linux and Mac OS X.
(Note that while SAM is distributed as a .NET executable for convenience of being able to produce a single cross-platform executable, SAM is by no means "developed in .NET" nor C#, and could well be deployed also on other platforms, eg. as Java, C++ or Objective-C. SAM itself is fully developed in Sling)
If you are using Linux or Mac OS X, see instructions below for the installation of Mono:
On Windows based operating systems that have the .NET Framework built-in, there is no need to use or install Mono (it is possible and fully supported to use Mono on Windows as well, however, if desired for any reason). The compiler is a standard .exe file, and can be executed as is, as long as the .NET framework is correctly installed and up to date.
The "installation" of the compiler is as simple as extracting the ZIP archive. You can then execute the compiler from where it was extracted to.
The installer package includes the following kind of directory structure:
bin/ - Executable files for the compiler samce - Shell script to execute on Unix/Linux operating systems samce.exe - .NET CLR executable *.dll - Supporting dynamic libraries slinglibs/ - Source code of libraries distributed with the compiler apidoc/ - API documentation for the distributed libraries
You will also notice that once you use the compiler, an additional directory named "profile" will appear here. All your personal configuration, installations and other cached files will be stored there.
Of notable importance are the following:
Execute samce under the bin directory on Linux and Mac OS X to invoke the compiler.
Execute samce.exe under the bin directory on Windows to invoke the compiler.
Open the index.html files under the apidoc directory to browse the API documentation.
3. Using SAM CE
Use the command line of your operating system when executing the SAM compiler. When executing either samce (on Linux or Mac OS X) or samce.exe (on Windows) from the bin directory without any command line parameters, you should see the following kind of output (exact output may vary depending on compiler version):
SAM CE / 1.0.20170109-r163 @ .NET4 Copyright (c) 2016-2017 Job and Esther Technologies, Inc. All rights reserved Usage: samce [parameters] Available parameters: -debug - Enable verbose / debug output -disable-color - Disable colors from terminal output -dumb - Disable all terminal controls -noconfig - Do not read the configuration files -noprofile - Do not use any profile -profile=[directory] - Specify a profile directory -O<option>=[value] - Set compiler options Available actions: slingc - Compiler for the Sling programming language slinglibmgr - Manage shared installation of Sling libraries config - Manage the compiler configuration apidoc - Produce API documentation tracker - Track tasks, todos and fixmes
Controlling compiler output
The compiler includes the following command line switches to control the output of the compiler:
In normal operation, the compiler prints some amount of status information on the command line terminal where you execute it, but does not produce a great deal of details. However, if you execute the compiler using the -debug switch, the compiler will produce very verbose output containing a lot of information good for tracing, debugging and finding out sources of unexpected behavior. Especially when reporting problems, producing a -debug output is very useful.
In normal operation also, SAM uses terminal colors to highlight a number of things, including errors, warnings and debug messages. If there is a need to do so, you can use the -disable-color switch to turn off colors.
The -dumb switch will cause the compiler to disable all terminal control operations (including colors), and will cause the compiler to simply print text on the terminal without any formatting. This is good if your terminal does not (fully and properly) support the terminal control features used by SAM, and/or if you need to save the output to a file, or for some other reason need to produce a "text dump" of the output.
SAM maintains a concept of a "profile", which is a data directory somewhere on the storage filesystem of your device that contains files and settings that are used to personalize the functionality of the compiler. Notably, your profile will include the following: (1) your configuration settings, (2) globally used Sling libraries and (3) native libraries.
Your profile has a default location inside the directory where your compiler was extracted (as discussed above). If you do not specify otherwise, this default location is always used as the default. However, there are two parameters you can give to SAM to control the location of your profile:
samce -profile=<full-path-to-your-profile-directory> [other parameters]
You may use any valid directory path as the profile location. The directory does not need to be pre-existing, but will be created by SAM if necessary.
By using the -profile switch, you can configure several different configurations and setups of the compiler environment, possibly including different versions of the platform libraries and/or extension modules.
You can also specify the following:
samce -noprofile [other parameters]
When specifying -noprofile, the compiler uses no profile at all. Notably, there will be no custom configuration or common libraries. This ensures that the compiler operates fully in "default" mode with regards to all customization parameters. Use this if you need to make sure any of your customizations are not going to take effect.
Many functionalities within SAM can be configured by specifying "compiler options" that can be provided by the user in different ways. As part of the SAM framework, options can be provided either (1) via command line parameters or (2) via configuration settings stored in the profile.
1. You can specify any compiler options via the command line
samce -OoptionName=this-is-the-value [other parameters]
The command line parameter takes precedence, and overrides any values that may be previously configured in the profile.
2. You can specify compiler options via the profile
samce config set optionName this-is-the-value
Additionally, you may be able to specify compiler options through the project files of the programs you are compiling, such is the case eg. with Sling programs: See below for more details
Once you execute the above-mentioned command, the key/value pair will be saved as part of the currently selected profile, and will be enabled for all subsequent runs of the compiler. This is especially useful when configuring eg. paths for external tools or other permanent customizations.
There are different types of variable values that can exist in the configuration. The sample above operates on a string variable, where the value "this-is-the-value" is assigned to the key "option.name". However, it is also possible to define list variables that may contain several strings as their value. This can be done with the "add" subcommand:
samce config add myListVariable "first value" samce config add myListVariable "second value"
The above command would add the two string values to the list named "myListVariable".
You can also remove previously configured settings from the profile:
samce config unset optionName
This command would undo the command done earlier.
You can also clear all saved configuration settings using the "clear" subcommand:
samce config clear
After executing this command, all your configured settings will be removed.
4. Compiling Sling programs
The "slingc" (Sling Compiler) action of the SAM compiler is used to compile programs written in the Sling Programming Language. The "slingc" compiler action has a number of additional command line options of its own, which you can see by executing it without any additional parameters:
This will give you a listing of possible additional parameters, something like the following (will vary depending on the compiler version):
SAM CE / 1.0.20170109-r163 @ .NET4 Copyright (c) 2016-2017 Job and Esther Technologies, Inc. All rights reserved Usage: sam slingc [parameters] Available parameters: -rebuild - Rebuild the project (even if there are no changes) -rebuild-all - Rebuild the project and all dependencies -static - Incorporate all dependencies in one build unit -nostdlibs - Don't include any of the standard libraries -target=[target] - Specify the target platform -output=[output] - Specify the output directory -depend=[library] - Manually add a dependent library -lib=[name:path] - Specify the location of a library file -libdir=[directory] - Add a library directory -D<key>=[value] - Define preprocessor variables (application scope) -define:<key>=[value] - Define preprocessor variables (application scope) -define-global:<key>=[value] - Define preprocessor variables (application and all dependencies) [project-path] - Path to a project file or directory Available targets: html5 - HTML5 android - Android / Java iossim - iOS / Objective-C (simulator) iosdev - iOS / Objective-C (device) dotnet - .NET4 mono - Mono
Automatic installation of libraries
Note that when you execute samce slingc for the very first time on a new profile, you will not immediately see the above kind of information. Instead, you will see that the compiler performs certain installation tasks. This is the "automatic installation of libraries" of the Sling compiler: The libraries that are distributed as part of the compiler itself are being installed as part of the profile. This way, no manual installation of libraries will be needed, and the libraries will be immediately available after the installation.
Compiling a Sling project (pling)
To compile a Sling project using samce slingc, at its simplest, just specify the directory to the Sling project file (.pling) as additional parameter to the compiler:
samce slingc MyProjectDirectory/myproject.pling
If everything is well, the compilation should proceed.