Compiling Concurnas code?

Concurnas code can be compiled via the concc command line tool or via IDE which has support for Concurnas. Here we shall examine the concc command line tool. We can compile a .conc file as follows:

D:\work>concc hello.conc

The concc command line tool has the following syntax:

concc options sourcefiles/directories

There must be at least one sourcefile or directory provided as an argument. Source code files must have the .conc suffix to be compilable. If a directory reference is provided then this will be searched, including nested directories, for .conc files. Multiple entries can be delimited with a space.

If any .conc file has a dependency on a .conc file listed in the same directory, then the dependant .conc file will also be compiled.

By default the .conc files will be compiled in to one or more .class file per source file input, into the same directory as the original sourcefile. To override the output directory of the .class files, use the -d option described below. Where the output directory has been overridden, if it does not already exist, Concurnas will attempt to create it.

The directory hierarchy relative to the working directory of the concc call denotes the package name of the output .class files for .conc files specified in the sourcefiles. The root directory is the current working directory in which concc is run. The root working directory can be overridden using the -root option described below. All referenced source files are taken to be relative to this directory.

Where a directory is specified for compilation, the root of the directory is taken to be root for nested .conc files for the purposes of package name generation. The exception being where the specified directory path is fully qualified, in which case the base of the nested hierarchy will be taken as the root directory for package name generation purposes.

Sourcefiles and directories may also be prefixed with an element specific root directory. This will override the global root directory (if specified) or default working directory. The syntax for this is as follows:

root[sourcefiles or directories]

Using an element specific root is generally the easiest method by which one can perform compilation with correct package names for multiple source files existing across multiple directories.

Options?

There can be zero to many options specified on a call to concc

  • -d directory: Override the directory where .class files will be output. concc will try to create this directory if it does not already exist.

  • -a or -all: Copy all non .conc files from source directories to provided output directory (output directory is overridden with the -d option).

  • -jar jarName[entryPoint]?: Creates a jar file from all generated/copied files. Optional entryPoint class name may be specified which will be used to populate a META-INF/MANIFEST.MF file within the jar. Can only be used in conjunction with the -d option.

  • -c or -clean. Remove all generated files from output directory. Useful in conjunction with -jar option. Any generated jar files will not be removed.

  • -classpath path or -cp path: The classpath option enables one to override the CLASSPATH environment variable. Elements are delimited via ; and must be surrounded by "" under Unix based operating systems. Elements may consist of directories, .class file references or .jar file references.

  • -verbose: Provide additional compilation information including bytecode output.

  • -root directory: Override the root directory of javacc. Package names for .conc files will be generated relative to this.

  • -werror: Normally, warnings do not prevent class file generation, setting this tag will treat warnings as errors, thus preventing class file generation warnings are generated for the input .conc source file in question.

  • -J: JVM argument. Prefix jvm arguments with -J in order to pass them to the underlying JVM. e.g. -J-Xms2G -J-Xmx5G.

  • -D: System property. Prefix system properties with -D in order to pass them to the underlying JVM. e.g. -Dcom.mycompany.mysetting=108.

  • --help: List documentation for options above.

It is recommended that the -d directory option be used for all but the most trivial of compilations.

Examples?

Compile all code in .src relative to default working directory:

concc ./src

Compile all code in .src relative to default working directory but override the output directory, writing output classes to /classes:

concc -d ./classes ./src

As par previous example and (via -a option) copying all non .conc files to /release directory:

concc -a  -d ./release ./src

As par previous example but additionally packaging all files in output directory into a jar: release.jar and removing all copied files from the output directory except the output jar, release.jar:

concc -a -clean -jar release.jar -d ./release ./src

As par previous example but additionally specifying an entry point (com.mycompany.product.Start) the main method of which will be executed in the event of execution via the conc command:

concc -a -clean -jar release.jar[com.mycompany.product.Start] -d ./release ./src

Compile all code in .src relative to default working directory and Mycode.conc in extrasrc.

concc ./src ./extrasrc/Mycode.conc

As above but override the root of Mycode.conc to be extrasrc (thus the package name of the code in Mycode.conc will not be prefixed with extrasrc):

concc ./src ./extrasrc [Mycode.conc]

As above but override the output directory, writing output classes to /classes:

concc -d ./classes ./src ./extrasrc [Mycode.conc]

As above but with custom libraries (jars and classes) set on the classpath:

concc -cp ./include/MyLib.jar;./include/UtilClass.class -d ./classes ./src ./extrasrc [Mycode.conc]

JVM arguments?

Arguments (for example garbage collection and memory allocation tuning) may be applied to the underlying JVM executing concc by prefixing them with -J. For example:

concc -J-Xmx2g ./src ./extrasrc/Mycode.conc

System properties?

System properties may be specified on the command line when running concc by prefixing them with -D. For example:

concc -Dcom.mycompany.mysetting=108 ./src ./extrasrc/Mycode.conc

Adding concc to the path?

It is recommended that the <installDir>/bin be added to the system path in order to permit concc to be run from any path. Check your operating system documentation for details of how to do this. The Windows installer for Concurnas will perform this automatically, as will installation via the SDKMAN! platform.

Jar files?

Jar's are an excellent way of packaging code for organization and distribution. As seen above the concc tool is able to create these as described previously. Additionally the jar tool provided as part of the JDK can be used to achieve this objective.

Notes?

The first time the concc tool is executed, or when a new JVM environment upon which is its being executed is detected, an 'installation' will take place wherein Concurnas will set itself up to execute efficiently upon said JVM environment by caching a copy of the JDK. This can take up to a few minutes to complete.