Desktop Compiler

About Desktop Compiler

OmniMark Desktop Compiler is a compiler for the OmniMark programming language. It is used to generate compiled programs that can be run using OmniMark Concurrent Processing Engine or OmniMark Single Processing Engine. Compiled OmniMark programs can be run on any supported platform.

OmniMark Desktop Compiler will provide you with compile-time error messages.

Installing and Configuring OmniMark on Windows

On a Windows machine, you install OmniMark by running the OmniMark installer. You will be guided through the installation and licensing process.

You configure your copy of OmniMark by choosing from the options in the installation program. To change your configuration, re-run the installation program at any later time: you will be presented with the option of modifying your installation.

Include Files and Modules on Windows

OmniMark ships with a number of include (.xin) files, and modules .xmd. Your OmniMark programs can call the functions defined in these files. You can also write your own include files and modules, or obtain them from third parties. If you run OmniMark programs from source, OmniMark must be able to locate these files. When you install OmniMark on Windows, the installer records in the Windows registry the location of the include files. OmniMark can find these automatically. You can prevent OmniMark from searching the directories named in the registry with the -noenvarg or -noea command line option. If you want a specific OmniMark program to use a different set of include files or modules, you can specify their location using the -i command line option.

When searching for include files and modules, OmniMark searches in the following order:

  1. the current directory,
  2. paths specified on the OmniMark command line, and
  3. paths specified in the Windows registry.

Installing and Configuring OmniMark on UNIX

On a UNIX machine, you install OmniMark by untarring the files into a suitable directory. Once OmniMark is installed, you must license it. To license your copy of OmniMark you must request an authorization key from Stilo.

Licensing OmniMark Desktop Compiler on UNIX

To receive and install your license key, begin by running OmniMark Desktop Compiler with the -reqkeygen command-line option with the following arguments:

  1. the serial number you received when you purchased OmniMark,
  2. the email address you want the license key sent to, and
  3. a string of your choice that will let you identify the license key you will receive; this is useful if you are licensing several copies of OmniMark at once.
  4. the number of the port you select for Desktop Compiler to use; we recommend a number not less than 32000.

Capture the output in a file. For example, suppose that your serial number is SN-Yy3X-ptdi-gpa-u[4, the selected port number is 40999 and you want to save the request key in the file req.txt:

  omdc -log req.txt -reqkeygen "SN-Yy3X-ptdi-gpa-u[4" me@mycompany.com "Machine Sol23" 40999

OmniMark Desktop Compiler will generate a request key and write it to the specified file. Email the contents of req.txt in the body of a plain text email to reqauth@stilo.com. You will receive an authorization key by return email.

Create an environment variable called OMNIMARK_INFO and give it the value AUTH: followed by your authorization key. If you already have an OMNIMARK_INFO environment variable, you can add your new key to the end of the existing key using a semi-colon as a separator. For details on setting environment variables, consult the documentation for your shell or contact your system administrator.

Include Files and Modules on UNIX

OmniMark ships with a number of include (.xin) files, and modules .xmd. Your OmniMark programs can call functions in these files. You can also write your own include files and modules, or obtain them from third parties. If you run OmniMark programs from source, OmniMark must be able to locate these files. When you install OmniMark on a UNIX system, directories containing the include files and modules are not located automatically. You must do one of the following:

  • set the OMNIMARK_INCLUDE environment variable, or
  • use the -i command-line option.

When setting the OMNIMARK_INCLUDE variable under UNIX, paths should be separated by a colon. For details on setting environment variables, consult the documentation for your shell or contact your system administrator. You can prevent OmniMark from searching the directories named in the environment using the -noenvarg (or -noea) command line option. If you want a specific OmniMark program to use a different set of include files or modules, you can specify their location on the command line using the -i command line option.

When searching for include files and modules, OmniMark searches in the following order:

  1. the current directory,
  2. paths specified on the OmniMark command line, and
  3. paths specified in environment variables.

Running OmniMark Desktop Compiler

To compile an OmniMark program on Windows start a command line window by selecting Command Prompt from the Windows Program Menu; on UNIX, bring up a shell prompt.

To compile OmniMark programs,

  1. write and debug your program, and
  2. compile the program using the -s command-line option to specify the source file, and the -save command-line option to specify the filename of the compiled output.

Using arguments files

You can combine several command line options into a file called an arguments file. You then name the arguments file on the OmniMark Desktop Compiler command line using the -f command-line option. The command-line options in the arguments file will be read as if they had been entered on the command line. Arguments files are usually given the extension .xar. The following command line compiles the program program.xom and reads command line options from the file arguments.xar.

  omdc -s program.xom -f arguments.xar

If you place the -s argument into an arguments file, you can start OmniMark Desktop Compiler using an arguments file alone. The following command line causes OmniMark Desktop Compiler to read options, including the -s option, from the arguments file program.xar.

  omdc -f program.xar

When you create an arguments file, you should place command line arguments one per line, like this:

  #!/usr/bin/omdc -f
  -s program.xom
  -save program.xvc
  -i /opt/OmniMark/xin/
          

You can include the #! directive in an arguments file. It will be interpreted appropriately on a UNIX system and will generally be ignored on a Windows system. If used, the #! line must contain the -f command-line option, which causes OmniMark Desktop Compiler to read the arguments file.

You may include command line arguments meant for the OmniMark program as well as OmniMark Desktop Compiler arguments in an arguments file. Additionally, you can load one arguments file from inside another arguments file.

Command-line options

The command-line options for OmniMark Desktop Compiler are listed below. Many command-line options have short forms.

Compiling OmniMark programs

To compile an OmniMark program, specify the source file name using the -s command-line option, and the name of the compiled output using the -save command-line option:

  -s sourcefile.xom -save sourcefile.xvc
The -s command-line option can also be written -source or -src. The -save command-line option can also be written -csc.

You can specify the OmniMark program directly on the console (stdin) using the -term command-line option.

The identification banner can be suppressed using the -brief command-line option.

Specifying arguments files

To specify an arguments file that is to be read as part of the command line, use

  -f testprogram.xar
The -f command-line option can also be written -argsfile.

Generating function traces

To generate a function trace when the program is executed, compile the program using the -ftrace command-line option.

Controlling error messages

To set a maximum number of allowed error messages, use the -limit command-line option:

  -limit 100
The -limit command-line option can also be written -threshold.

To suppress the message output at the end of compilation giving the number of reported markup error and warning messages, use the -nocount.

Controlling warnings

The OmniMark compiler produces warnings in several classes.

  • ambiguity: A statement is ambiguous. The compiler may not have interpreted the statement in the way you intended.
  • deprecated: The keyword you used is deprecated. You should use the modern equivalent.
  • dead-code: A section of code cannot be reached when your program is executed.
  • pattern: A pattern can match zero characters.
  • performance: A section of code can negatively impact performance.
  • redundancy: The same declaration or modifier (or equivalent) is used more than once. OmniMark will ignore the duplicates.
  • risky-code: A section of code may have an unexpected effect.
  • uninitialized-data-access: A shelf is not explicitly initialized or assigned any value anywhere, but its value is used.

By default, the OmniMark compiler will display all these classes of warnings except for uninitialized-data-access, which is ignored. You can change how each class of warning is handled using the following command line options:

  • to ignore the class of warnings, use -warning-ignore warning-class,
  • to report only a summary of the class of warnings, use -warning-summary warning-class,
  • to report the warning and continue compiling, use -warning-report warning-class, and
  • to promote the class of warnings to an error, use -warning-error warning-class.

You can also use the all warning class to quickly apply the same command-line option to all classes of warnings. For example,

  -warning-error all -warning-ignore uninitialized-data-access
would report warnings for any warning other than uninitialized-data-access.

The -warning and -warnings command line options used in previous version of OmniMark no longer have any effect on the compiler.

Locating include files and modules

To specify a path to include files or modules, use

  -i path
The -i command-line option can also be written -include.

To force OmniMark to ignore include paths specified in environment variables and Windows registry entries, use

  -noenvarg
The -noenvarg command-line option can also be written -noea.

Information and logging

The -log command-line option is used to specify a file to which OmniMark will write log messages generated by the OmniMark program:

  -log testprogram.log
To append to the log file instead of overwriting its contents, use the -alog command-line option:
  -alog testprogram.log

To add program execution statistics, including memory usage and execution times, to the log, use

  -stats

You can find out which version of OmniMark you are using the -version command-line option.

To display the authorization key for OmniMark, or to view diagnostic information in the case of an authorization failure, use the -authkey command-line option.

Generating a license request key (port locking)

To generate a licence request key, use the -reqkeygen command-line option, providing it with a serial number, an email address, an identifying string, and a port number. For example,

  -reqkeygen "SN-Yy3X-ptdi-gpa-u[4" me@mycompany.com "Machine Sol23" 40999
The output goes to the log stream. It can be captured using the -log command-line option; however, in this case the -log command-line option must appear before the -reqkeygen.

Prerequisite Concepts