Next: , Previous: , Up: Usage   [Contents][Index]


3.2 Compiling coNCePTuaL programs

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:

--backend (abbreviation: -b)

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.

--quiet (abbreviation: -q)

The --quiet option tells ncptl and the chosen backend to output minimal status information.

--no-link (abbreviation: -c)

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.

--no-compile (abbreviation: -E)

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.

--keep-ints (abbreviation: -K)

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.

--lenient (abbreviation: -L)

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.

--filter (abbreviation: -f)

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.

--output (abbreviation: -o)

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.

--program (abbreviation: -p)

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.

--help-backend (abbreviation: -H)

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


Footnotes

(2)

As an aside, --help-backend is essentially equivalent to ‘-- --help’; the --help-backend synonym is provided merely for convenience.


Next: , Previous: , Up: Usage   [Contents][Index]

Scott Pakin, pakin@lanl.gov