Command Line Reference
If you have followed the installation guide, you have a silver
script in your ~/bin
which is typically invoked as follows:
silver grammar:to:build
If you do not want to use the silver
script, or are on a platform other than Linux, you will likely want to write a build script that looks something like the following:
java -Xss4M -Xmx1800M -jar $SILVER_HOME/jars/silver.composed.Default.jar grammar:to:build
In both cases grammar:to:build is the name of the grammar to compile. By default, the Silver compiler will look for the directory ./grammar/to/build
from where you run the silver script.
The optional command-line flags are described below.
The common optional flags used with Silver are:
-
-o
jar-name- Changes the name of the generated jar file to the specified name. (Include the
.jar
)
- Changes the name of the generated jar file to the specified name. (Include the
-
--clean
- Ignores generated files from previous runs, and rebuilds everything.
-
-I
paths- Instructs Silver to look for grammars in the specified directories before looking in those specified in
GRAMMAR_PATH
. (Or the defaults, of the current directory and thegrammars
directory where Silver is installed.)
- Instructs Silver to look for grammars in the specified directories before looking in those specified in
Less common:
-
--copperdump
- By default, a dump file containing information about the parser is generated only when LALR conflicts are detected, to aid in debugging the grammar. This flag will force a dump to occur even without errors. This may be useful in debugging parse errors that you think shouldn’t be happening: copper reports the parser state, and with the assistance of this information, may reveal what is going wrong.
-
--warn-all
-
Perform some extra analysis. This includes a modularity analysis that will help find, for example, missing equations.
If you want to see the generated flow-types and dependencies, then add the
--dump-flow-graph
flag.More information on the modular well-definedness analysis can be found here.
-
-
--mwda
- Perform the modular well-definedness analysis and report any violations as errors (rather than warnings).
-
-G
path- Specifies where to store Silver-generated temporary files. This overrides the value found in
SILVER_GEN
. (And the default is in thegenerated
directory where Silver is installed.)
- Specifies where to store Silver-generated temporary files. This overrides the value found in
Note: If you encounter a strange build error, try again with the --clean
flag. There are a few relatively rare build bugs that can still cause generated files to become stale.
Most uses of Silver should not require any adjustments to environment variables but they are documented here nonetheless.
-
GRAMMAR_PATH
- A colon separated list of paths to search for grammars. By default, this is set to include the current directory and the
grammars
directory in the Silver distribution. Generally, if you need Silver to look in other directories using the-I
switch is preferable.
- A colon separated list of paths to search for grammars. By default, this is set to include the current directory and the
-
SILVER_HOME
- The location of the Silver jar files. If the
silver
script is used, this flag is set there. If running Silver by calling theRunSilver.jar
file directly this may not need to be set as the jar file will set it automatically.
- The location of the Silver jar files. If the
-
SILVER_GEN
- The directory to generated temporary files within. This is set by default to the
generated
directory in the Silver distribution. An alternative to modifying this variable is to simply symlink this directory to the directory you wish to store temporary files in.
- The directory to generated temporary files within. This is set by default to the
For the silver
script, there is also
SVJVM_FLAGS
- Used to adjust flags sent to the JVM. For example,
SVJVM_FLAGS="-Xss8M -Xmx4000M -verbose:gc" silver grammar:to:build
(bash syntax) will give the JVM more memory and print some information every time a garbage collection happens.
- Used to adjust flags sent to the JVM. For example,
If the grammar specified on the command line to build also contains a main
function, then the resulting jar file will be executable. main
functions should have the following basic form:
function main
IOVal<Integer> ::= args::[String] ioin::IO
{
return ioval(ioin, 0);
}
For an explanation of how IO works in Silver, see IO Functions. The integer value wrapped inside IOVal
is the exit status of the program (0 is success.) And of course, the command line arguments are provided as a list of strings.
Simple examples of main functions can be found in every tutorial distributed with Silver.
Under support/nailgun
there are two scripts for running nailgun
on Silver jars. These require nailgun
of course and the scripts specifically require bash
. (On lab machines the scripts will find a Nailgun build under our project space automatically. On Ubuntu machines, you can apt-get install nailgun
and it’ll work.)
Nailgun runs everything in one JVM, saving repeated warm-up time. For largish test suites, this is possibly huge: our ableC test suite went from 45 minutes to 2.
To use these scripts, run ./install-sv-nailgun
in support/nailgun
. This requires ~/bin
and bash.
To use Nailgun, first initialize your bash shell with . sv-nailgun
. Note that’s “dot space” not “./”. This ‘sources’ the script into your bash shell, setting some environment variables and adding some functions. If it fails, there should be some sort of error message.
Next you initialize the jar you want to run repeatedly with sv-serve <jarfile>
. Unless an error appears, this should work.
After that, you can call that jar repeatedly with sv-call <args...>
. Each of these will re-use the JVM.
When done, call sv-serve-stop
to stop that JVM.
Enjoy the speedups.
Mac OS X Bug: you probably need Homebrew. The default sed
command on macOS is broken somehow and this will cause errors when you run sv-call
complaining that it can’t find exactly the right class that it should be able to find. The trouble is that there’s a unprintable trailing carriage return that should be stripped out, but apparently isn’t. Install GNU sed instead and everything should be okay.