Next: Supplied backends, Previous: The coNCePTuaL GUI, Up: Usage [Contents][Index]
The coNCePTuaL compiler is called ncptl and is, by default, installed into /usr/local/bin. Executing ncptl --help produces a brief usage string:
Usage: ncptl [--backend=<string>] [--quiet] [--no-link | --no-compile] [--keep-ints] [--lenient] [--filter=<sed expr>] [--output=<file>] <file.ncptl> | --program=<program> [<backend-specific options>] ncptl --help ncptl [--backend=<string>] --help-backend |
The usage string is followed by a list of installed backends.
The following list describes each compiler option in turn:
Specify the module that coNCePTuaL should use as the compiler
backend.
ncptl must be told which backend to use with
either --backend=backend
or by setting the environment variable
NCPTL_BACKEND to the desired
backend. Running
ncptl --help
lists the available backends. Most coNCePTuaL backends
are code generators. For example,
c_mpi
causes ncptl to compile
coNCePTuaL programs into C using MPI as the
communication library. However, a backend need not generate code
directly—or at all. The
c_trace
backend (see The c_trace
backend), for instance, supplements the code generated by
another backend by adding tracing output to it.
ncptl searches for backends first using NCPTL_PATH, an environment variable containing a colon-separated list of directories (default: empty); then, in the directory in which coNCePTuaL installed all of its Python files; and finally, in the default Python search path. Non-directories (e.g., the .zip archives used in newer versions of Python) are not searched.
If no backend is specified, ncptl runs the given coNCePTuaL program through the lexer, parser, and semantic analyzer but does not generate an output file.
The --quiet option tells ncptl and the chosen backend to output minimal status information.
By default, ncptl instructs the backend to compile and link the user’s coNCePTuaL program into an executable file. --no-link tells the backend to skip the linking step and produce only an object file.
By default, ncptl instructs the backend to compile and link the user’s coNCePTuaL program into an executable file. --no-compile tells the backend to skip both the compilation and the linking step and to produce only a source file in the target language.
coNCePTuaL backends normally delete any files created as part of the compiling or linking process. --keep-ints tells ncptl and the chosen backend to preserve their intermediate files.
The --lenient option tells the compiler to permit certain constructs that would otherwise result in a compilation error. First, using the same command-line option (either the long or short variant) for two different variables normally generates an ‘Option opt is multiply defined’ error. (See Command-line arguments, for a description of how to declare command-line options in coNCePTuaL.) --lenient tells the coNCePTuaL compiler to automatically rename duplicate options to avoid conflicts. Only the option strings can be renamed; the programmer must still ensure that the option variables are unique. Second, using a variable without declaring it normally produces an error message at compile time. Passing --lenient to ncptl tells the compiler to automatically generate a command-line option for each missing variable. This is convenient when entering brief programs on the command line with --program (described below) as it can save a significant amount of typing.
The --filter option applies a
sed
-style substitution expression to the
backend-translated code (e.g., a .c
file output by the
c_udgram
backend or a .tex file output by
the
latex_vis
backend) before the backend compiles
it. The --filter option can be used
multiple times on the command line; filters are applied in the
order specified. Substitution expressions must be of the form
‘s/pattern/replacement/flags’,
although the ‘/’ characters can be replaced by any
other character. pattern is a regular expression;
replacement is an optional replacement string; and,
flags is a sequence of zero or more modifiers from the
set {‘i’, ‘l’, ‘m’,
‘s’, ‘u’, ‘x’}, as described
in the Python
Library Reference. For example, ‘i’ means to perform a
case-insensitive substitution. In addition, the ‘g’
flag performs a global search-and-replace instead of replacing only
the first occurrence of pattern. An important difference
between --filter and sed is
that omitting the ‘g’ flag instructs
--filter to make at most one
substitution total while it instructs sed to
make at most one substitution per line.
ncptl normally writes its output to a file with the same base name as the input file (or a.out if the program was specified on the command line using --program). --output lets the user specify a file to which to write the generated code.
Because coNCePTuaL programs can be quite short --program enables a program to be specified in its entirety on the command line. The alternative to using --program is to specify the name of a file containing a coNCePTuaL program. By convention, coNCePTuaL programs have a .ncptl file extension.
Describe additional options that are meaningful only to the specified backend. The --backend option must be used in conjunction with --help-backend.
The following—to be entered without line breaks—is a sample command line:
ncptl --backend=c_mpi --output=sample.c --program='Task 0 sends a 0 byte message to task 1 then task 1 sends a 0 byte message to task 0 then task 0 logs elapsed_usecs/2 as "Startup latency (usecs)".'
ncptl stops processing the command line
at the first unrecognized option it encounters. That option and all
subsequent options—including those which ncptl would
otherwise process—are passed to the backend without interpretation
by
ncptl. Furthermore, the -- (i.e., empty)
option tells ncptl explicitly to
stop processing the command line at that point. For example, in the
command ncptl --backend=some_backend --lenient myprogram.ncptl
-- --program, ncptl will process
the --backend and
--lenient
options but will pass --program to the
some_backend
backend even though ncptl
has its own --program
option.2
As an aside, --help-backend is essentially equivalent to ‘-- --help’; the --help-backend synonym is provided merely for convenience.
Next: Supplied backends, Previous: The coNCePTuaL GUI, Up: Usage [Contents][Index]