Compiler Manpage

NAME

fregec.jar - command line compiler for the Frege language

SYNOPSIS

java -Xss2m  [-Dfrege.javac=javac-command] -jar fregec.jar [ FLAGS ] ITEM ...
java -jar fregec.jar -version
java -jar fregec.jar -repl

DESCRIPTION

The compiler operates either in normal mode or in make mode. Make mode can be selected with the -make option. See following subsections for a description.

The compiler reads Frege source files and produces Java source files that are normally subsequently compiled to class files. A class file produced this way contains meta-information about the compiled module in the form of Java annotations. These annotations are read by the compiler when the corresponding module is imported by another module.

Unless Java compilation is disabled (see -j option below), the Frege compiler needs a way to run a Java compiler. If the JVM the Frege compiler is running in belongs to a JDK installation, the internal compiler provided by the JDK is being used. Otherwise, the program javac is tried. This behavior can be overwritten by specifying the initial portion of the command to use (just the command name in the most simple case) in the property frege.javac. When the command name is internal, again the JDK compiler will be used; in this case the property serves only to provide additional options the user might want.

For example, when running under JDK 8, to get class files usable with JRE/JDK 7 one could use the following command:

java -Xss2m  -Dfrege.javac="internal -source 1.7 -target 1.7" -jar fregec.jar ...

Normal Mode

The given ITEMs are processed in the order given in the following way:

1. if it is a frege source file, then this file gets compiled.
2. if it is a directory, all frege source files found below it are compiled. The order of processing of individual files is undefined.
3. if it is a module name, the corresponding source file is looked up in the source path and gets compiled.

As of 3.22.524, it is assumed that no dependencies exist between the source files, so they will all be compiled in parallel.

Make Mode

In make mode, all source files given on the command line or found in directories given on the command line are first parsed to find out the module name and their dependencies. Likewise, if a module name is given, its corresponding source file is looked up in the source path and gets parsed.

The result of this dependency analysis is an initial set of modules (and, since 3.24.400, java classes) that will get (re)compiled unless they are up to date. This set gets subsequently extended by the modules that are found as dependencies during parsing. The dependencies are also parsed in turn if there is a corresponding source file, in order to find even more dependencies transitivly. Which are, of course, parsed to get still more dependencies ...

The handling of modules specified on the command line and modules found during dependency analysis differs insofar as for the latter it is ok when there is no source file present in the sourcepath. If a corresponding class file can be found, it is assumed that it is a library module which is up to date and does not need a rebuild.

The results of parsing the source files are kept until it is time to compile the corresponding modules, and then the compilation process is simply continued based on the previously obtained results. Hence, the overhead of the dependency analysis is minimized.

A module will be recompiled in the following cases:

• There does not exist a corresponding class file in the target path, or the source file is newer than the class file.
• Any of the dependencies of a module needs to get recompiled.

Recompilation of a module takes place only after all dependencies have been checked and their recompilations, if any, were successful. The order of the ITEMs on the command line is thus irrelevant, they are processed in dependency order.

Make mode employs concurrency whenever possible. Parsing of source files can be done concurrently with any other activity. Modules that do not depend on each other can be compiled in parallel. If some module needs to get compiled, all modules that depend on it can be compiled as soon as the code generation finishes successfully, and the java compilation phase runs concurrently.

New since 3.24.400: The compiler finds out on what java classes a frege module depends, and if the corresponding source files exist in the sourcepath, it compiles them with javac before frege compilation continues for that module.

Interpreter (REPL)

If the REPL code is included in the distribution (which should be the case from version 3.24.400 on), the commands

java -jar fregec.jar --repl
java -jar fregec.jar -repl
java -jar fregec.jar repl
java -jar fregec.jar

start the interactive command line interpreter. No additional command line arguments are allowed.

FLAGS

Directories and Paths

• -d directory

Specifies target directory for *.java and *.class files. The directory is also added to the class path. It must exist prior invocation of the compiler. Defaults to the current directory .

• -fp path

Specifies additional directories, ZIP files or JAR files to add to the class path. The names are to be separated by the path separator of the platform (i.e. : for Unix, ; for Windows). Class files of imported modules are searched in that path. The current class path of the running JVM plus the target directory are always on the class path.

• -sp sourcepath

Specifies one or more directories where frege source files can be found. Default is the current directory. When the compiler searches for a source file for some module x.y.Z it looks for x/y/Z.fr below each directory in the source path, in the order given.

The source path is also handed down to the Java compiler.

Modes of operation

• -inline optimize code by inlining inline-able functions
• -O optimize generated code even more. Implies -inline
• -make operate in make mode
• -j don't compile generated java files
• -target x.y compile code for Java version x.y, the default being the version of the JVM the compiler is running in. This will also pass -nowarn -source x.y -target x.y to the java compiler, unless x.y is the current version.

Diagnostics

• -comments Generate commented Java code. This makes code generation substantially slower, but can be useful at times.

• -hints Print more detailed error and more warning messages.

• -nowarn Not recommended. Suppress warnings like those about incomplete pattern matches.

• -v be chatty and emit more or less useless statistical information.

• -explain i[-j]

Print some debugging otuput from type checker regarding line(s) i (to j ). May help to understand otherwise inexplicable type errors better.

Presentation of types

These options determine how types are presented in compiler diagnostic messages, but also in tools that use the compiler code like IDE and documentation tool. Two choices are to be made: should the compiler use unicode or ASCII symbols? And, from which alphabet to draw characters to construct type variable names?

• -ascii use ASCII symbols for forall, ->, => and :: and also refrain from using exotic characters in the generated java code.
• -symbols use ∀, →, ⇒ and ∷ instead. This is the default.
• -latin construct variable names from the latin alphabet.
• -greek construct variable names from the greek alphabet. This is the default.
• -fraktur construct variable names from fraktur letters.

Here is the type of return with -ascii -latin and -symbols -fraktur for contrast:

return :: Monad m => a -> m a
return ∷ Monad 𝖒 ⇒ 𝖆 → 𝖒 𝖆

Other

• -enc charset

The character set of frege source files. When not specified, UTF-8 is assumed. The value DEFAULT selects the default charset of the running JVM.

Note that intermediate Java source files will always be in UTF-8.

• -prefix name

Prefix for package names. Used in compiler development to avoid interference between running and compiled classes.