5—External Compiler Interface

5 External Compiler Interface

This section describes the External Compiler Interface (ECI). ECI is a
specification for interfacing with third-party compiler and linker programs. ECI
programs translate generic compiler and linker commands into commands
targeting specific compiler tools. This allows compiler, linker, archiver, etc.
commands to be issued in a portable format which then is translated to conform
to conventions and requirements of specific tools. For the remainder of this
document, compiler is used as a term to describe all such code-generation
tools.

OPNET Modeler includes several scripts and utility programs which implement
the ECI translation for popular Windows and Linux compilers. Using the
External Compiler Interface Specification, you can generate interface programs
to allow the use of compilers not directly supported in the release.

External Compiler Interface Specification

External Compiler Interface (ECI) programs expect command-line arguments
consisting of abstract commands as input for translation. The format of the
command-lines is designed to be easily-parsed. It is a series of alternating
labels and values. Each label is a short token. Each value is a string which will
usually be integrated unaltered into the final command line passed to the
compiler. Certain label tokens may require multiple values; in this case, each
value is passed as a separate parameter, and the list is terminated by a special
“end-of-list” token.

ECI translators are required to return the compiler’s exit status to their caller.
This provides the ability to determine whether a particular abstract command
that it generated had succeeded.

A feature of Windows-based compilers is the ability to read options from a

separate file and treat them as though they had been specified on the command
line. Such a file is sometimes called a response file (this term is used in this
section). The response file is intended as a work-around for the relatively small
size limit of command strings under Windows.

For more information, see:

• Tokens

• Commands

Tokens
The following tokens are used in abstract commands:

• OP <operation>—specifies the operation to perform. Values can be one of

arch, bind, bind_so, comp, or comp_so.

EI-5-1 OPNET Modeler/Release 16.1

 5—External Compiler Interface

• IF <filename>—specifies the input file to the compilation process. This may

be a source file, an object file, or a response file which lists a number of
object files.

• OF <filename>—specifies the output file of the compilation process. This

may be an object file, a static library, a shared object (dynamic-linked library),
or an executable program.

• XF <filename>—specifies a file containing a list of symbols which are to be

exported from a shared object. This is specified under Windows and can be
ignored for Linux platforms.

• FL <flags…>—specifies one or more flags to be passed through to the

compiler. This list is terminated by a token consisting of a double colon.
These flags will usually be specified by the user via a preference.

• IN <include dir>—specifies the name of an additional directory in which the

compiler should search for header files. Since a single additional directory is
specified, this is not a list token.

• LB <libraries…>—specifies one or more libraries to be passed to the linker.

The libraries may be specified by the user via a preference, by
OPNET Modeler, or both.

• VM—specifies that the script or compiler print to standard output the exact
compilation or linking command (including flags) it sent to the operating
system. This is useful for gathering information when you have trouble
compiling or linking code.

• TA <target>—specifies the target architecture for compilation. <target> can

be 32bit or 64bit.

Note—Printing the command typically causes the top-level compilation or

linking operation to fail. Therefore, use this token only when performing
diagnostics or debugging.

OPNET Modeler/Release 16.1 EI-5-2

5—External Compiler Interface

Commands
Four different operations require the generation of an abstract command:

• Compiling on page EI-5-3

• Binding Executables on page EI-5-4

• Binding Shared Objects on page EI-5-5

• Archiving on page EI-5-6

For each operation, a template command is shown, followed by a description of

each value in the command with its origin.

Compiling

<comp_prog> OP <operation> IF <input_file> OF <output_file>

IN <include_dir> FL <comp_flags…> ::

where comp_prog and comp_flags come from preferences, while the remaining
options are generated by OPNET Modeler. The value of operation is comp_so
if the object code must be relocatable (if it is to go into a shared object), or comp
if the object code does not need to be relocatable. Information about this
command is listed in the following table.

Table 5-1 Compile Command Options

Component Description

comp_prog The name of the ECI translator which will generate a command or
commands to compile the input file to the output file.

operation One of comp or comp_so.

input_file The name of the source file to compile.

output_file The name of the destination object file.

include_dir The name of an include directory to add to the include path of the
compiler.

comp_flags User-specified flags to pass on to the compiler.

End of Table 5-1

EI-5-3 OPNET Modeler/Release 16.1

 5—External Compiler Interface

Binding Executables

<bind_static_prog> OP bind IF <input_file> OF <output_file>

FL <bind_static_flags> :: LB <archive> <bind_static_libs> ::

where bind_static_prog, bind_static_flags, and bind_static_libs come from

preferences, and the rest are generated by OPNET Modeler. archive is the input
archive library file (i.e. the “.si.a” file). Information about this command is listed
in the following table.

Table 5-2 Bind Executables Command Options

Component Description

bind_static_prog The name of the ECI translator which will generate a command or
commands to link the input file with the archive and static libraries
to form an output file executable.

input_file The name of the main object file to link with the archives and other
libraries.

output_file The name of the destination executable file.

bind_static_flags User-specified flags to pass on to the linker.

archive Name of archive library to include in the executable.

bind_static_libs User-specified static libraries to include in the linking.

End of Table 5-2

OPNET Modeler/Release 16.1 EI-5-4

5—External Compiler Interface

Binding Shared Objects

<bind_shobj_prog> OP bind_so IF <input_file> OF <output_file>

XF <export_file> FL <bind_shobj_flags> :: LB <libraries> ::

where bind_shobj_prog and bind_shobj_flags come from preferences, and the

rest are generated by OPNET Modeler. The libraries are only specified under
Windows, where they are necessary for generating DLLs. Here, input_file will
be a response file listing the object files that will go into the shared library and
export_file lists the external symbols in the library (not necessary under Linux).
Information about this command is listed in the following table.

Table 5-3 Binding Shared Objects Command Options

Component Description

bind_shobj_prog The name of the ECI translator which will generate a command or
commands to link the input files with the libraries to form a shared
object library.

input_file The name of the response file which contains the names of object
files to link into the shared library.

output_file The name of the destination shared object library.

export_file The name of a file listing external symbols in the library (Windows
only).

bind_shobj_flags User-specified flags to pass on to the linker.

libraries Libraries to include in the link phase, necessary under Windows to

generate shared object libraries. These libraries are specified by
OPNET Modeler.

End of Table 5-3

EI-5-5 OPNET Modeler/Release 16.1

 5—External Compiler Interface

Archiving

<arch_prog> OP arch IF <input_file> OF <output_file>

where arch_prog is a preference. As above, input_file will be a response file.

Information about this command is listed in the following table.

Table 5-4 Archiving Command Options

Component Description

arch_prog The name of the Eci translator which will generate a command or
comma to place the files listed in the input response file into a
static library.

input_file The name of the response file which contains the names of object
files to link into the static library.

output_file The name of the destination static object library.

End of Table 5-4

OPNET Modeler/Release 16.1 EI-5-6