The Eqela SAM compiler is a compiler and a compiler framework that can support multiple programming languages for both input and output, and is able to perform various transformation to the programs it processes

Filed under

1. Overview

SAM

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

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.

2. Installation

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:

More information: How to install 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 profiles

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.

Compiler options

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:

samce slingc

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.

Further information

The Sling Programming Language

Sling Language Reference



Twitter Facebook LinkedIn Youtube Slideshare Github