vici1

Usage

Overview

vici is a compiler for compiling Objective C objects into C, or directly into a binary object file (by automatically invoking an external C compiler).

Command line options that are not recognized by objc are passed on to cc(1).

-boehm

The preferred interface to turn on garbage collection, is to use the -gc flag (which currently is equivalent to -boehm).

-boehm links against objcrtgc.a which is a version of the runtime library, compiled with -DOBJCRT_BOEHM. This option also adds the library libgc.a (a mark-and-sweep garbage collector, needs to be installed for this option to work) to the list of libraries that are automatically linked into the program.

-Bprefix

Use prefix as prefix for the bin, include and lib directories when searching for binaries, include files and libraries. The default prefix is set to the installation directory (e.g. /usr/local). The environment variable OBJCDIR overrides the default, and this option can be used to override the value of the environment variable, on the command line.

-c

Produce a .o file but do not link. Equivalent to -Fo.

-C

When used with the -E option, this option will preserve comments in the preprocessed code. Otherwise, this option is equivalent to -Fi, i.e. generate C code, by translating Objective C into C, but do not run the C compiler to produce a .o file.

-check

Implemented for the binary driver objc.exe only. Forces the driver to print a command whenever it is supposed to invoke some tool using a system() call. Commands are simply printed, they are not executed. This is the default configuration of the Macintosh MPW driver.

-cplus

Use the C++ compiler instead of the C compiler to compile the output of objc1. The driver will automatically select this mode objcpls1 for files ending with a .cc or .mm suffix (C++ files or Objective-C compiled by C++ respectively).

-cthreads

Link against the runtime library objcrtth.a which is a thread-safe version of the objcrt.a runtime library (compiled with -DOBJCRT_CTHREADS).

-dl

Combine a number of object files into a dynamic module, to be loaded by dlopen() or similar, into a running Objective-C program. This option makes sure the necessary code is generated to automatically initialize Objective-C classes that are loaded into the program.

-dollars

Passes flags to the C compiler to allow dollar characters in identifiers. Only tested with GNU C.

-dynamic

Must be specified to link a program that will load dynamic modules (modules that are built with -dl). Attempts to link against objcrt.so and objpak.so shared runtime libraries, if those libraries can be found.

-dynamic passes on -noShared to the stage 1 compiler and registers the function _objcInitNoShared as runtime initialization function. This is strictly speaking not needed on UNIX, but essential when using DLLs on Windows, so it is done on all platforms.

In addition, -dynamic causes on some platforms to link against the necessary libraries that define dynamic linking functions. For example, on Linux it adds a -rdynamic flag. On HP-UX it passes a -E flag to the link editor. On Windows, (with the WATCOM driver), it adds a -br flag to use the DLL versions of the WATCOM runtime.

-E

Preprocess input and write output to the stdout.

-Fletter

Stop at the compilation stage specified by letter. Letter can be one of o (-Fo is equivalent to -c), or other file suffixes such as i,c,j etc.

-gc

Turn on garbage collection. Client programs compiled with this flag use +new to allocate objects (as usual), but do not have to send a -free message to destroy objects.

-g

Produce debugging symbols and attempts to link against objcrt_g.a and objpak_g.a runtime libraries with debug information, if they can be found. Since objc is also emitting by default linetags that refer to the original source file, it is possible to step through the code using any C debugger.

-help

Print overview of compiler switches.

-i

Generate a TDF capsule (.j file) for use with the tcc compiler and do not link. Equivalent to -Fj.

-Idir

Add dir to the search path for include files.

-inlinecache

Generate inline cache code for calls to _imp() messenger. The inline cache messenger associates to each message expression its own cache, and will in many cases bypass the default objcrt messenger.

It is safe to use this option to produce binary libraries of objects; the libraries can later be used both from within programs that are compiled either with or without the -inlinecache option.

-import

Pass flags to the C preprocessor to do the traditional Objective-C constructs # import and // on which we usually don't depend. Note that it's also possible to set the environment variable CPP to a preprocessor that's newline-terminated-comments capable, or to use the cvtimport(1) utility so that the flag is not needed.

-jfoo

Find and add a TDF library foo.tl.

-Jdir

Add dir to the search path for TDF libraries.

-lfoo

Find and add a library libfoo.a (or corresponding shared library, depending on the system).

-Ldir

Add dir to the search path for libraries.

-main function

Emit runtime initialization code as first statement in function. The default function name is main, but this can be changed using this option if it's not desirable for some reason to compile the main() function using objc.

-mpwtool

Macintosh specific. Generates an MPW tool. Sets creator type to the MPW type and adds the libraries defined in the environment variable OBJCMPWLIBS.

-noBlocks

Define the preprocessor symbol OBJC_BLOCKS as 0 (by default the symbol is defined as 1), and make the parser refuse to parse Objective-C blocks. See the documentation of the Block class for more information.

-noCache

Turn off global Objective C messenger cache. This option can be used with -inlineCache. Sets the objcrt variable noCacheFlag to 1. The program can selectively turn on caching by setting the variable to 0.

-noI

Do not search header files in the directories of the runtime (objcrt) and of the collection class library (objpak).

-noLibs

Do not link against the runtime (objcrt) and the collection class library (objpak).

-noNilRcvr

Messages to nil, the NULL Object, are handled by the nilHandler funtion. This option registers a handler that aborts the process.

-noCategories

Do not allow (parse) categories. It is still possible to use the method addMethodsTo: instead.

-noFiler

Do not automatically link the AsciiFiler into the program. Do not automatically generate filer code for class implementations. See the documentation on the show, storeOn and readFrom methods, and the AsciiFiler class, for more information.

-noFwd

Generate code for, and calls to, the traditional C messenger, _imp(), instead of calls to our forwarding C messenger, fwdimp(). Programs compiled with -noFwd compile faster and are significantly smaller in executable size, but cannot make use of Object's doesNotUnderstand: method. Libraries and object files compiled with, or without, -noFwd can be freely mixed, but message forwarding will only work for those classes that were compiled with message forwarding turned on.

-noPostlink

Allows to generate code for auto-init with compilers that are configured to generate by default code for postlink.

-noSelfAssign

Do not allow self as left hand side in an assignment. This is related to the use of instance variables in factory methods.

-noTags

Suppress generation of line tags in temporary files. Normally, line tags as expected by the C compiler are generated to indicate the line numbers of the original source, so that diagnostics will be issued against the Objective C source, not against the generated C output.

-nostdinc

Do not search header files in the standard include directories. This option is system specific, i.e. must be supported by the cpp(1) preprocessor that is being used; it differs from the -noI option.

-O

Enable the optimizer. Whether it is possible to specify both -g and -O depends on the C compiler that is being used.

-oneperfile

Allow only one class implementation per compilation unit, as the original Stepstone compiler does. The compiler will generate slightly different structures when this flag is used. The runtime is properly initializing both code variants, and binary object files compiled with or without this flag can be linked into the same program.

-objc

Treat files ending with .c as Objective C source files. Normally, files ending with a .m are assumed to be Objective C files, and .c files are assumed to contain plain C.

-otb

Use object tables. This option causes the compiler to generate code that uses a double indirection for Object identifiers (handles, instead of pointers). It also links against runtime libraries called otbcrt.a and otbpak.a, because modules or libraries compiled with the -otb switch cannot be mixed with modules that were compiled without this option.

-pg

Produce profiling information for use by gprof.

-pic

Generate position independent code (PIC) on systems that support it, for building shared libraries. On some systems, this option translates to -fpic, on other systems (e.g. HP-UX) it is equivalent to +z.

-ppi

Include a set of compatibility header files in the default include path (for compatibility with Stepstone ICpak101). Also, allow classes to be defined using 3.x Productivity Products International syntax. This is used for compiling Brad Cox' Smalltalk to Objective-C translator. Implementations of classes start with '=' instead of the usual @implementation keyword. Superclasses still need to be declared with an @interface part, but the class that is being defined, itself, does not need an interface part.

-postlink

Generate code for postlink. The default is not to do this. If you compile with this option on, you cannot combine object files for Objective C source with the usual link editor ld. Instead, if you use -postlink, you will be using our postlink (1) link editor processor, which does additional processing after linking. Programs compiled with postlink use a somewhat faster objcrt initialization, at the expense of longer link times. Use the combination of the flags -postlink and -retain to produce a file _postlnk.c that contains a list of all the Objective C modules that are linked into your program.

-prod

Combine target independent independent TDF capsules into a TDF archive (a .ta file). This option is passed on to the tcc (1) compiler, the archive name can be set with -o. The resulting platform independent .ta file can be specified on the command line as an ordinary .a file.

-pthreads

Link against the library libpthreads.a and the runtime library objcrtth.a which is a thread-safe version of the objcrt.a runtime library (compiled with -DOBJCRT_PTHREADS).

-quiet

Disable copyright notice. Same as -q.

-retain

Do not remove intermediate C files. Normally, intermediate C code files are removed after objc has made the C compiler compile them.

-refcnt

Generate code for reference counting. Assignments of object variables are translated towards calls to the idassign() function and code to increment and decrement reference counts is emitted for each compound statement. Only variables of type id are being controlled by this option.

-sioux

Macintosh specific. Generates a SIOUX tool. Adds the libraries defined in the environment variable OBJCSIOUXLIBS.

-static

On systems that support dynamic linking and the -static compiler flag, this prevents linking with shared libraries.

-Tprefix

Use prefix as prefix for temporary files (such as .P, .c, .i files) that are generated by the precompiler. For example, -T/scratch/ (note the trailing slash) will place files in the /scratch directory. Alternatively, the environment variable TMPDIR can be used to specify the directory that should be used.

-undef

Undefine all built-in C preprocessor symbols. This option is system specific, i.e. must be supported by the cpp(1) preprocessor that is being used.

-unbuf

Run objc1 in unbuffered output mode. The default is to use block buffering. Unbuffered output mode is useful for debugging code generation of the precompiler.

-version

Print version of compiler and quit.

-v

Print commands that are being executed by the driver script. Same as -verbose.

-verbose

Print commands that are being executed by the driver script. Equivalent to -v.

-w

Suppress all warnings.

-Wletter,option

Add option to the list of options passed to the tool identified by letter. Letter can be l for the link editor, c for the C compiler, p for the C preprocessor, or o for the stage 1 Objective C compiler. For example, -Wp,-x passes the option -x to cc when it is called with the -E flag to do preprocessing.

-wClassUsedAsType

Suppress warnings when class names are used as types. The compiler will translate pointers to classnames to "id".

-wUndefinedMethod

Suppress warnings for methods that are not prototyped. The compiler will assume that the return value and argument types of such methods is "id".

-Wall

Passed on the GNU C compiler for enabling compiler warning messages.

-xstr strings

Run the (modified) BSD program xstr(1) after running the Objective C compiler. This option can somewhat reduce the size of Objective C selector tables of the executable ( xstr will extract selector strings out of the translated Objective C sources, assemble the strings in a file called "strings", and will cause the runtime to use a single, shared table of strings). This could also speed up runtime initialization as selectors don't have to be uniqued anylonger at startup.

-Yenv

Use the specified environment. This is for the TenDRA tcc compiler. Valid values are -Yansi, -Yposix, -Yunix95 etc.

Environment

The most useful environment variable for setting options for objc is probably OBJCOPT. It was introduced in version 1.3.7 of the compiler (port to Windows95). The environment variable OBJCDIR is kept for backward compatibility with older compilers.

OBJCOPT

The environment variable OBJCOPT can hold a list of options that is always prepended to the command line arguments of objc.
For example, on UNIX, using the ksh shell :

export OBJCOPT="-q -B$HOME/objc1.1.1"

This would set the top location of the distribution, and would, in addition, always suppress copyright messages. On Windows95, the syntax is :

set OBJCOPT=-q -B\objc

OBJCDIR

This variable can hold the top location of the objc distribution. For example:

for ksh: export OBJCDIR="$HOME/objc1.1.1"

for csh: setenv OBJCDIR "$HOME/objc1.1.1"

$OBJCDIR/bin and $OBJCDIR/man can be added to $PATH and $MANPATH respectively.

OBJCPATHSEP

This environment variable, if set, is a string that will be used as path separator instead of the default separator. Applies to both objc and objc1.

TMPDIR

If set, temporary files will be placed in this directory. The -T option overrides the value set by TMPDIR.

CC

The environment variable CC can optionally hold the name of a C compiler that is used to compile intermediate C files.

CPP

The environment variable CPP can optionally hold the name of a C preprocessor that is used to preprocess Objective-C input. The driver is normally configured with a default value.

CPPFILTER

The environment variable CPPFILTER can optionally hold the name of a C program that is to be ran after the C preprocessor. The tool will be invoked with two arguments : the name of the input file, and the name of the output file.

OBJCRTMSG

This environment variable is not strictly related to the compiler, but rather used by the runtime and hence, by all Objective-C programs. It can be set to either stderr or a filename to which messages should be logged. For every message, class of the receiver and name of the selector are printed on a line. This file can quickly become very large; it is block buffered, unless OBJCRTDBG is set, in which case it is line buffered.

OBJCRTDBG

Like OBJCRTMSG, this variable is consulted by the runtime. It can be set to either stderr or a filename to which messages of the dbg() function should be logged. If this variable is set, output for OBJCRTDBG and OBJCRTMSG is line buffered.