iraf-dev 2.16.1+2018.03.10-2 / usr / lib / iraf / unix / boot / spp / xc.hlp

.help xc Oct89 softools
.ih
NAME
xc -- portable IRAF compile/link utility
.ih
USAGE
xc [flags] files
.ih
FLAGS
.ls 10 -a
To support VMS link options file.  Next file is taken to be the VMS name
of a link options file.  This is primarily for using long lists of files
or libraries and not for actual VMS Linker options, since XC adds continuation
characters where it believes it is appropriate.
.le
.ls 10 -C
Tells fortran to do array bound and other checking.
By default no checking is done.  From DCL fortran usually
does array and overflow checking which is not used here.
.le
.ls 10 -c
Tells \fIxc\fR not to link, i.e., not to create an executable.
.le
.ls 10 -d
Causes debug messages to be printed during execution.
.le
.ls 10 -F, -f
Do not delete the Fortran translation of an SPP source file.
.le
.ls 10 -g
Generates debugging information and (for VMS), links in the debugger.
.le
.ls 10 -h
Causes the executable to be linked as a host program, i.e., without the
IRAF main and without searching the IRAF libraries, unless explicitly
referenced on the command line.  Used to compile and link host (e.g., Fortran)
programs which may or may not reference the IRAF libraries.
.le
.ls 10 -i2
Tells fortran to use I*2 by default.
.le
.ls 10 -i4
Tells fortran to use I*4 by default.
.le
.ls 10 -l\fIlib\fR
This tells the linker which libraries besides the standard
ones to include.  These must be either on the current
directory, or in an IRAF system library (lib$ or hlib$).
The library specification must be immediately after the option as in
"-lxtools".  No other option may follow the 'l' option in the same
argument as in -lxtoolsO.	
.le
.ls 10 -L
Creates a list file. VMS specific.
.le
.ls 10 -M, -m
Tells the linker to create a link map.
.le
.ls 10 -n
Not really supported under VMS since "normal" users
cannot install images.  In Unix this is just a link
option to make a shareable image.
.le
.ls 10 -N
Same as -z for VMS.
.le
.ls 10 -Nh [filename]
This tells xpp that the foreign definitions in the
file specified should be used in preference to
standard include files.	
.le
.ls 10 -o
This flag redirects the output of the compile if used in
conjunction with -c option or specifies where the executable
or object is to be placed.  If not given the first file
name is used to obtain the name for the executable or
object.
.le
.ls 10 -O
Optimize object code produced; this is now the default, but this switch
is still provided for backwards compatibility.
.le
.ls 10 -p pkgname
Load the package environment for the named external package, e.g.,
"xc -c -p noao file.x".  If the same package is always specified
the environment variable or logical name PKGENV may be defined at the
host level to accomplish the same thing.  The package name \fImust\fR
be specified when doing software development in an external or layered
package.
.le
.ls 10 -P
Check portability.  This should be used all of the time in IRAF,
but the VMS C compiler forces the use of non-standard
constructs in some cases.  Also <stdio.h> and <ctype.h> get
complaints for the above reason.  This may be used and probably
should when working with Fortran due to Dec non-standard
extension.
.le
.ls 10 -q
Disable optimization.  Opposite of -O.  Object code will be optimized
by default.
.le
.ls 10 -s
Strips all symbols and debugging information.
.le
.ls 10 -S
Same as -s for VMS.
.le
.ls 10 -v
Verbose mode.  Causes messages to be printed during execution telling
what the \fIxc\fR program is doing.
.le
.ls 10 -w
Suppress warnings.				
.le
.ls 10 -X, -x
Compile and link for debugging.  In VMS/IRAF, links in the VMS debugger
and symbols.
.le
.ls 10 -z
Create a non-shareable image (default).
.le
.ih
DESCRIPTION
XC is a machine independent utility for compiling and linking IRAF
tasks or files.  The XC utility may also be used to compile and/or link
non-IRAF files and tasks.  The VMS version of XC supports all of the
important flags except -D which VMS C doesn't support in any way.
It can be used to generate fortran from xpp or ratfor code, to compile any
number of files, and then link them if desired.  XC accepts and maps IRAF
virtual filenames, but since it is a standalone bootstrap utility the
environment is not passed, hence logical directories cannot be used.

The following extensions are supported by the VMS version of xc:
.x, .r, .f, .ftn, .for, .c, .mar, .s, .o, .obj, .a, .olb, .e, .exe.
It is suggested that everyone stick with the iraf virtual file name extensions.
These are : .x, .r, .f, .c, .s, .o, .a, .e. The mapping of these to their
VMS counterparts is:

.ks
.nf
     .x -> .x    SPP code
     .r -> .r    Ratfor code
     .f -> .for  Fortran code
     .c -> .c    C code
     .s -> .mar  Macro assembler code
     .o -> .obj  Object module
     .a -> .olb  Library file
     .e -> .exe  Executable Image
.fi
.ke


XC is available both in the CL, via the foreign task interface, and as
a standalone DCL callable task.  Usage is equivalent in either case.  Upper
case flags must be quoted to be recognized (the upper case flags will be
done away with at some point).
.ih
EXAMPLES
Any upper case flags in the following examples must be doubly quoted in
the CL, singly quoted in VMS, to make it to XC without VMS mapping
everything to one case.  Omit the "-x" flag on a UNIX system.

1. Compile and link the source file "mytask.x" to produce the executable
"mytask.e".

	cl> xc mytask.x

2. Translate the file "file.x" into Fortran.

	cl> xc -f file.x

3. Compile but do not link "mytask.x" and the support file "util.x".

	cl> xc -c file.x util.x

4. Now link these for debugging.

	cl> xc -x file.o util.o

5. Link the same files without the VMS debug stuff, but link in the library
-ldeboor (the DeBoor spline routines) as well.

	cl> xc file.o util.o -ldeboor

XC is often combined with \fImkpkg\fR to automatically maintain large packages
or libraries.
.ih
BUGS
The -S flag should generate assembler
output but does not presently do so in the VMS version.  All case sensitive
switches should be done away with in both the UNIX and VMS versions of the
utility.
.ih
SEE ALSO
mkpkg, generic
.endhelp