Flag options syntax

Except for the -W, -D, and -U flag options, all flag options that are supported by the c89 utility are supported by the xlc utility with the same semantics. The xlc utility does not recognize constructs such as -Wl,I or -Wl,p. All other aspects of the -W flag are the same as with the c89 utility. -D and -U flag options are not preprocessed by the xlc utility. Instead, they are converted to the DEFINE and UNDEFINE native options and are passed to the compiler. The xlc utility also supports several additional flag options, which are described below:

-#

Displays language processing commands but does not invoke them; output goes to stdout.

>>- -#---------------------------------------------------------><

-B

Determines substitute path names for programs such as the assembler and binder, where program can be:

• a (assembler)
• c (z/OS® XL C/C++ compiler)
• l (binder)
• L (IPA Link)

>>- -B--+--------+--+--------------+---------------------------><
        '-prefix-'  '- -t--program-'   

Note:

1. The optional prefix defines part of a path name to the new programs. The compiler does not add a / between the prefix and the program name.
2. To form the complete path name for each program, the xlc utility adds prefix to the program names indicated by the -t option. The program names can be any combination of z/OS XL C/C++ compiler, assembler, IPA Link and binder.
3. If -Bprefix is not specified, or if -B is specified without the prefix, the default path (/usr/lpp/cbclib/xlc/bin/) is used.
4. -tprograms specifies the programs for which the path name indicated by the -B option is to be applied.
5. -Bprefix and -tprograms options override the path names of the programs that are specified inside the configuration file indicated by the -Fconfig_file option.
   Example: To compile myprogram.c using a substitute compiler and binder from /lib/tmp/mine/, enter:

   xlc myprogram.c -B/lib/tmp/mine/

   Example: To compile myprogram.c using a substitute binder from /lib/tmp/mine/, enter:

   xlc myprogram.c -B/lib/tmp/mine/ -tl

-F

Names an alternative configuration file (.cfg) for the xlc utility.

Suboptions are:

• config_file (specifies the name of an xlc configuration file.)
• stanza (specifies the name of the command used to invoke the compiler. This directs the compiler to use the entries under stanza in the config_file to set up the compiler environment.)

>>- -F--+-config_file--+-----------+-+-------------------------><
        |              '-:--stanza-' |   
        '-:--stanza------------------'   

Note:

1. The default configuration file supplied at installation time is called /usr/lpp/cbclib/xlc/etc/xlc.cfg. Any file names or stanzas that you specify on the command line override the defaults specified in the /usr/lpp/cbclib/xlc/etc/xlc.cfg configuration file.
2. The -B, -t, and -W options override entries in the configuration file indicated by the -F option.

Example: To compile myprogram.c using a configuration file called /usr/tmp/mycbc.cfg, enter:

  xlc myprogram.c -F/usr/tmp/mycbc.cfg

-M

Instructs the compiler to generate a dependency file or dependency files that can be used by the make utility. By default, the dependency file name and path is the same as the -o compile option but with .u suffix. Dependency file name can be overridden by the -MF option. The default suffix can be modified through "usuffix" configuration file attribute.

The compiler will generate as many dependency files as there are source files specified.

-M is the equivalent of specifying -qmakedep.

>>- -M---------------------------------------------------------><

Example: To compile myprogram.c and create an output file named myprogram.u, enter:

xlc -c -M myprogram.c

Example: The following is a simple makefile that uses -M feature. You can refer to z/OS UNIX System Services Programming Tools for more information about the make utility and makefiles.

CFLAGS = -M -qLSE=lib1 -qfloat=ieee

all: program

# Compile recipe; 	will also regenerate dependencies, used on the
next compile %.o: %.c
	xlc -c $(CFLAGS) $^ 

program: file1.o file2.o
	xlc $(CFLAGS) -o program $&

#This line will include the generated file1.u and file2.u only
if they exist .INCLUDE .IGNORE : file1.u file2.u

-MF

If -M or -qmakedep is specified, this option is used to override the file path name of the dependency file.

>>- -q--makedep--+------------+--------------------------------><
                 '- -MF--file-'   

In the syntax, file can be either a file name or a directory. If a directory is specified, the default dependency file name is used (as per the -M option) and placed in this directory. The directory must exist. If a relative file name is specified, it is relative to the current working directory.

Note:

1. The argument of file can not be the name of a dataset.
2. If the file specified by -MF already exists, it will be overwritten. Moreover, if the output path specified does not exist or is write-protected, an error message will be issued.
3. If you specify a single file name for the -MF option when compiling multiple source files, each generated dependency file overwrites the previous one. Only a single output file will be generated for the last source file specified on the command line.

Example: You can refer to the following table for detail usage of -M and -MF:

Table 1. Example of using -M and -MF

Description	Command	Dependency File
-MF is not specified	xlc -c -M t.c	./t.u is generated
	xlc -M -c -o obj.o t.c	./obj.u is generated
	xlc -c -M -o dir/ t.c	./dir/t.u is generated if ./dir is writable
-MF specifies a file	xlc -c -qmakedep -MF dep.u t.c	./dep.u is generated
	xlc -c -o obj.o -M -MF ../dep.x t.c	../dep.x is generated
	xlc -c -M -MF dir/dep.d a.c b.c	./dir/dep.d is generated for b.c only.
-MF specifies a directory	xlc -c -M -MF dir/ a.c b.c	./dir/a.u and ./dir/b.u are generated for a.c and b.c respectively if ./dir/ is writable

-O

Optimizes generated code.

>>- -O---------------------------------------------------------><

-O2

Same as -O.

>>- -O2--------------------------------------------------------><

-O3

Performs memory and compile-time intensive optimizations in addition to those executed with -O2. The -O3 specific optimizations have the potential to alter the semantics of a user's program. The compiler guards against these optimizations at -O2 and the option -qstrict is provided at -O3 to turn off these aggressive optimizations.

>>- -O3--------------------------------------------------------><

-O4

Equivalent to -O3 -qipa and -qhot.

>>- -O4--------------------------------------------------------><

-O5

Equivalent to -O3 -qipa=level=2 and -qhot.

>>- -O5--------------------------------------------------------><

-P

Produces preprocessed output in a file that has a suffix that is defined by isuffix, isuffix_host, ixxsuffix, and ixxsuffix_host. The default for host files is .CEX and for z/OS UNIX files is .i.

As with the -E option, the -C option can be combined with the -P option to preserve the comments.

-S

Produces an assembler source file for C source that is compiled with the METAL compiler option. The -o option can be used to override the default file name produced by -S. The default file name is the C source file name with the suffix determined by the ssuffix and ssuffix_host attributes in the configuration file.

When you specify the -o option, the assembler source file name is based on the name specified with the option. For example, when you specify xlc -S -qmetal -c -o foo.x hello.c, the output assembler source file name is foo.x. The following specifications have the same result:

xlc -S -qmetal hello.c
xlc -S -qmetal -o hello.s hello.c
xlc -S -qmetal -c hello.c 
xlc -S -qmetal -c -o hello.s hello.c 

-t

Adds the prefix specified by the -B option to the designated programs, where programs are:

• a (assembler)
• c (z/OS XL C/C++ compiler)
• L (Interprocedural Analysis tool - link phase)
• l (binder)

        .-------.   
        V       |   
>>- -t----+-a-+-+----------------------------------------------><
          +-c-+     
          +-L-+     
          '-l-'     

Note: This option must be used together with the -B option.

If -B is specified but the prefix is not, the default prefix is /usr/lpp/cbclib/xlc/bin/. If -Bprefix is not specified at all, the prefix of the standard program names is /usr/lib/cbclib/xlc/bin/.

If -B is specified but -tprograms is not, the default is to construct path names for all of the standard program names: a, c, L, and l.

Example: To compile myprogram.c so that the name /u/new/compilers/ is prefixed to the binder and assembler program names, enter:

    xlc myprogram.c -B/u/new/compilers/ -tla

-W

Passes the listed options to a designated compiler program where programs are:

• a (assembler)
• c (z/OS XL C/C++ compiler)
• I (Interprocedural Analysis tool - compile phase)
• l (binder)

Note: When used in the configuration file, the -W option requires the escape sequence back slash comma (\,) to represent a comma in the parameter string.

   .------------------------------.   
   |             .--------------. |   
   V             V              | |   
>>--- -W--+-a-+----,--directory-+-+----------------------------><
          +-c-+                       
          +-I-+                       
          '-l-'                       

Example: To compile myprogram.s so that the option map is passed to the binder and the option list is passed to the assembler, enter:

  xlc myprogram.s -Wl,map -Wa,list

Example: In a configuration file, use the \, sequence to represent the comma (,):

  -Wl\,map,-Wa\,list