Dec 212017
 
Clip is the command-line compiler driver (MAKE system) that Nantucket should have written for Clipper.
File CLIP110.ZIP from The Programmer’s Corner in
Category Dbase Source Code
Clip is the command-line compiler driver (MAKE system) that Nantucket should have written for Clipper.
File Name File Size Zip Size Zip Type
CLIP.CFG 215 148 deflated
CLIP.DOC 37211 10294 deflated
CLIP.EXE 25530 14889 deflated
CLIP5.CFG 191 133 deflated

Download File CLIP110.ZIP Here

Contents of the CLIP.DOC file
































CLIP Version 1.10

Clipper(R) Compiler Driver

Extrasensory Software
4450 Murietta Avenue, #8
Sherman Oaks, CA 91423

(c) 1990








1. INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . 1
What is Clip? . . . . . . . . . . . . . . . . . . . . . 1
What Clip Isn't . . . . . . . . . . . . . . . . . . . . 1
Copyright and License . . . . . . . . . . . . . . . . . 2
Advertising . . . . . . . . . . . . . . . . . . . . . . 2
Acknowledgements . . . . . . . . . . . . . . . . . . . . 3

2. INSTALLATION . . . . . . . . . . . . . . . . . . . . . . 4
About Configuration Files . . . . . . . . . . . . . . . 4

3. RUNNING CLIP . . . . . . . . . . . . . . . . . . . . . . 6
The Command Line . . . . . . . . . . . . . . . . . . . . 6
Command-line Options . . . . . . . . . . . . . . . . . . 7
Option Descriptions . . . . . . . . . . . . . . . . . . 9
Option Precedence . . . . . . . . . . . . . . . . . . 11
Command Files . . . . . . . . . . . . . . . . . . . . 11
Using Clip Instead Of Make . . . . . . . . . . . . . . 12

4. SOURCE FILE OPTIONS . . . . . . . . . . . . . . . . . 13

5. CONFIGURATION . . . . . . . . . . . . . . . . . . . . 15
Environment Variable Settings . . . . . . . . . . . . 15
Compilation Commands . . . . . . . . . . . . . . . . . 16







1. INTRODUCTION

1.1. What is Clip?

Clip is the command-line compiler driver that Nantucket should
have written for Clipper. Instead, we got CL.BAT and (with
Clipper 5.0) RMAKE. The first only works for simple programs
composed of a single module, and the second (while powerful) is
confusing and requires a lot of work to use.

Clip comes somewhere between the two. It was inspired by the
compiler drivers included with most C compilers (like CL.EXE with
Microsoft C, or "cc" with UNIX C compilers). Originally, our
intent was to provide a single command that would compile and
link one or more Clipper source modules, optionally along with
other object files and third-party libraries.

Somewhere along the line things got out of hand. It turned out
that allowing response files and a "check timestamps" option
could make Clip into an easier-to-use alternative to RMAKE and
other make utilities, so those went into the pot. Then Clipper
5.0 added a bunch of new compiler options, and Clip had to
support those too.

Finally, we found ourselves getting confused over some of the new
options in 5.0, trying to remember that THIS program had to be
compiled with "-n" and "-w" while THAT one needed "-v". So Clip
gained the ability to look at source file headers to see what
options each module needs. The rest is...well, history?

1.2. What Clip Isn't

Clip is not a compiler or linker; it's just a program that RUNS
compilers and linkers. Obviously, you must have those other
programs before you can run them. So, at very least you'll need
a copy of Clipper (Summer '87 or 5.0) and a linker.

This version of Clip does not support overlays. There is no way
tell it to produce an overlaid executable (except with .RTLink,
which overlays all Clipper code by default). Right away, you can
see that it's not the solution to all your giant programming
problems, but it IS useful for small and mid-sized projects. If
you like the features of Clip but need overlays, you may want to
let Clip compile your source files, but use a conventional link
response file to link the executable.








- 1 -







1.3. Copyright and License

Clip and this document are copyright 1990 by:

Extrasensory Software
4450 Murietta Ave., #8
Sherman Oaks, CA 91423
(818) 981-8367

Clip is FREE software. You may use it and give it to others to
use as long as you do not charge for it, other than reasonable
distribution charges. You may upload it to public or commercial
BBSs or include it with your software or source code. However,
you must distribute the complete package, including documentation
and all other files, in unmodified form.

1.4. Advertising

Well, we have to get SOMETHING out of this. Extrasensory
Software writes and sells Clipper development tools. We hope
that, if you like Clip, you may be interested in some of our
commercial products, like:

Telepathy: The best serial communications library today.
Supports Xmodem (and /CRC and -1K), Ymodem (and -G), Zmodem,
and Kermit protocols, background event handling, and much
more.

The Extrasensory PostScript Library: The first PostScript
library for Clipper. Produce publication-quality text and
graphic output from your PostScript printer.

For information on any of our products, write us at the address
above, or contact us by any of these electronic media:

BIX: irae or drifkind
CompuServe: 76702,672
TelePath: ira
Usenet: uunet!cstreet!esp!inquiry














- 2 -







1.5. Acknowledgements

The following names mentioned in this document are trademarks or
registered trademarks:

UNIX: AT&T Bell Laboratories.
BLINKER: BLINK, Inc.
Turbo C, TASM, TLINK: Borland International.
WarpLink: hyperkinetix, Inc.
Microsoft C, MASM: Microsoft Corp.
Clipper: Nantucket Corp.
.RTLink: Pocket Soft, Inc.
PLINK86+: Sage Software, Inc. (formerly a trademark of Phoenix
Technologies, Ltd.)







































- 3 -







2. INSTALLATION

You should have received these files as part of the package:

CLIP.EXE The compiler driver.
CLIP.CFG Configuration file for Clipper Summer '87.
CLIP5.CFG Configuration file for Clipper 5.0.
CLIP.DOC This document.

To install Clip for Summer '87, copy CLIP.EXE and CLIP.CFG into a
directory on your DOS search path. You will probably want to
edit CLIP.CFG, with an ordinary text editor, to include your
preferred default options.

To install Clip for 5.0, copy CLIP.EXE and CLIP5.CFG into a
directory on your DOS search path. Rename CLIP5.CFG to CLIP.CFG.
You will probably want to edit...oh, you get the idea.

To install Clip for both Summer '87 and 5.0, copy CLIP.EXE,
CLIP.CFG, and CLIP5.CFG into a directory on your DOS search path.
Make another copy of CLIP.EXE, calling it CLIP5.EXE, in the same
directory. Each copy of Clip will look for a configuration file
of the same name when you run it (so CLIP.EXE uses CLIP.CFG and
CLIP5.EXE uses CLIP5.CFG). You will probably want to edit BOTH
CLIP.CFG and CLIP5.CFG. If you like, you can make other copies,
giving them other names, but make sure there is an appropriate
configuration file for each copy.

2.1. About Configuration Files

This is not the right place to describe all the options you can
place in a configuration file, and they will all be explained in
detail later. However, we should mention here that you almost
certainly DO want to change the default configuration. Unless
you specify otherwise, Clip assumes you want to use PLINK86+ to
link your executables. If that's all right, you can go play with
Clip now.

So that you won't have to read the entire manual first (we don't
like to read manuals either), here's how to change the default
linker. Using your program editor, edit the file CLIP.CFG. The
first line of the file says:

# Default options:









- 4 -







The "#" means that this line is a comment. Below it, insert
another line containing one of these options:

-Lb to use BLINKER
-Lm to use Microsoft LINK
-Lp to use PLINK86+
-Lr to use .RTLink
-Lt to use TLINK
-Lw to use WarpLink

The first two lines of the file should now look something like
this:

# Default options:
-Lb

Now save CLIP.EXE.

If you do not have the LIB environment variable set in your
AUTOEXEC.BAT to the path where you keep your Clipper libraries,
you should fix that now. Clip looks for the standard libraries
using this variable and will not be able to find them if you do
not have LIB set.

If you have both the Summer '87 and 5.0 versions of Clipper
installed and want to use them both, you'll need to read the
section on configuration files in this document. Sorry.


























- 5 -







3. RUNNING CLIP

3.1. The Command Line

Run Clip by entering the command name ("clip", or whatever name
you have given the executable file) at the DOS prompt, optionally
followed by a series of options and/or file names. What happens
next depends on the options and file names (if any) you give. In
the simplest case, if you give one or more Clipper source file
names, Clip will use the Clipper compiler to compile each source
file, then (assuming no errors) link them all into a single
executable using the linker you specified in the configuration
file.

There are three kinds of arguments to the "clip" command: file
names (which may be source, object, or library files), command-
line options, and command file names. Options all begin with
either a "-" or "/" character, and command file (also known as
response file) names begin with a "@". Anything else is assumed
to be an input file name.

Clip looks at the extension on each input file name to decide
what kind of file it is and how to treat it. Any name with no
extension is treated as a .PRG file. The extensions and kinds of
files Clip knows how to deal with are:

.PRG Clipper source files
.CLP Clipper source file lists
.C C language source files
.ASM Assembly language source files
.OBJ Compiled object files
.LIB Library files.

NOTE: With Clip, you do NOT use "@" for .CLP files. "@" is for
Clip command files (extension .CMD), which are a different thing
entirely.

The order in which you give input file names does not matter to
Clip, except that it uses the name of the first input file with
the extension changed to .EXE as the default executable file
name. The order of the files does matter to the linker, though,
so in general the first name given should be the main module, and
you may have to give the names of third-party libraries in some
specific order as well. You can mix source, object, and library
names in any order; Clip will make sure that the linker sees all
the object files before any of the libraries. (However, don't
put a library name first unless you want to use that for the
executable file name!)





- 6 -







If you do not give any file names on the command line, Clip will
look for and read a default command file called CLIP.CMD in the
current directory. This feature makes it easy to use Clip as a
substitute for a "make" utility. See the section on command
files for details on the format of this file.

Clip searches for files with the extensions .PRG, .CLP, .C, and
.ASM in the current directory (or the directory given in the file
name). It searches for .LIB files using the path given by the
LIB environment variable, and for .OBJ files using the path given
by the .OBJ environment variable.

Examples:

clip myprog
Compiles and links MYPROG.PRG.

clip main other.clp
Compiles MAIN.PRG and OTHER.CLP and links them to produce
MAIN.EXE.

clip myprog debug.obj
Compiles MYPROG.PRG and links it along with DEBUG.OBJ.
Searches for DEBUG.OBJ using the path given by the OBJ
environment variable.

clip myprog funcky.obj funcky.lib
Compiles MYPROG.PRG and links it along with FUNCKY.OBJ
(found using the OBJ environment variable) and FUNCKY.LIB
(found using the LIB environment variable).

3.2. Command-line Options

Command-line options all start with either a "-" or "/" character
(your choice; they mean the same thing). The option format is
similar to that used by CLIPPER.EXE, but with several important
differences:

* Options are CASE SENSITIVE. I know this will annoy some of
you, but we felt it was necessary to prevent the names of
some of Clip's special options from conflicting with Clipper
compiler options.

* You may string options together. That is, instead of using:

-n -v -w (or /n/v/w)

you may give them all at once as:

-nvw (or /nvw)



- 7 -







* When an option requires an argument (like the "-u" option in
Clipper 5.0), you are allowed to put spaces between the
option letter and the argument. Where Clipper 5.0 requires:

-umyheader.ch

Clip allows:

-u myheader.ch

as well. In Clipper 5.0, "-u" with no argument tells the
compiler not to use any standard header file. Since Clip
allows a space after "-u", you have to use "-u -" or "-u-"
to tell it not use use a standard header file.

* Options and file names may be mixed in any order on the
command line. The options do not have to come last. The
order of names and options does not matter; Clip processes
all of the options first, then goes back to handle the file
names.

* Options which can be turned on or off (like "-v") can be
followed by a "-" to turn that option off (like "-v-").
This is useful if the configuration file or command file
turns an option on, but you want it off for a particular
compile.

Most of Clip's options are the same as options to CLIPPER.EXE.
They are listed here (options marked with a "*" are available
only in Clipper 5.0):

-a Automatic memvar declarations
* -b Debugging information
* -d id[=value] #define identifier
* -i path #include file path
-l No line numbers
-m Compile one module only
* -n No implicit starting procedure
-q Compile quietly
* -r library Request library ("-r -" = none)
* -u header Use standard header ("-u -" = none)
-v Assume memory variables
* -w Enable warnings

These CLIPPER.EXE options are NOT supported:

-o path Object file path
* -p Generate preprocessed output file
-s Syntax check only




- 8 -







The rest of Clip's options do not correspond to CLIPPER.EXE
options. They are (see complete descriptions below):

-c Compile only, don't link
-e exename Change executable file name
-f Force link even if not out of date
-h Print "help" message
-L {bmprtw} Select linker
-M Generate link .MAP file
-OL option Pass option to linker
-t Check timestamp, compile if source changed
-V Display commands before executing them

3.3. Option Descriptions

-c Normally, Clip will compile all source files then link them
to produce an executable. With "-c", it compiles the source
files as usual but does not link them.

-e exename
By default, Clip gives the executable file the same name as
the first input file, minus any drive and path specifier,
and with the extension changed to .EXE. "-e" allows you to
specify a different file name, or to give a complete name
including a drive and path.

-f If you use the "-t" (timestamps) option, Clip will not
relink the executable if none of the source files had to be
recompiled. "-f" instructs it to ignore the executable's
timestamp and perform the link anyway. This is useful if
you wish to use a different linker.

-h Enter "clip -h" for a short description of the command-line
options.

-L {bmprtw}
"-L" followed by one letter tells Clip which linker to use
to produce an executable program:

-Lb BLINKER
-Lm Microsoft LINK
-Lp PLINK86+
-Lr .RTLink
-Lt TLINK
-Lw WarpLink

-M Generate link map file. By default, Clip does not produce a
map file when it links a program.





- 9 -







-OL option
Passes "option" directly to the linker. Usually, this will
be a switch or option to enable some special linker feature
which Clip does not support directly. For example, with
WarpLink you can use:

-OL /clpi

to enable incremental linking. The option may contain more
than one word if surrounded by double quotes. To link a
Clipper 5.0 program using a .RTLink pre-linked library
(PLL), you might use:

-OL "pll base50"

-t Check timestamps before compiling. Clip will compare the
timestamp on each source file to its corresponding object
file and compile only if the source file is newer (or the
object does not exist). For .CLP files, it checks the
timestamp on the .CLP file and all the .PRG files listed in
it and recompiles if any of them are newer.

Normally, if you specify "-t" Clip will not relink the
executable unless one or more object files is newer than the
executable (which will normally be the case if any of them
were recompiled). The "-f" option overrides this and forces
a link.

"-t" is most useful when placed in a command file, along
with a list of sources.

-V Most of Clip's job involves running other programs: the
Clipper compiler, a linker, and possibly a C compiler or
assembler. To check that it is running them correctly, or
just for amusement, you can give this option to make Clip
print each command line before executing it.

Examples:

clip myprog -Lm
Compiles MYPROG.PRG, and links it using Microsoft LINK.

clip -Lm myprog
Same as the previous example.

clip myprog /Lm
Same as the previous example.

clip myprog/Lm
This is NOT legal in the current version of Clip. Options
must be separated from file names by spaces. Your humble
programmer is too lazy to fix it right now.

- 10 -







clip myprog -e menu
Compiles MYPROG.PRG and links it (using the default linker)
to produce MENU.EXE.

clip myprog -emenu
Same as the previous example.

clip main mod1 mod2 mod3 -t
Compiles whichever of MAIN.PRG, MOD1,PRG, MOD2.PRG, and
MOD3.PRG have changed since the last time they were
compiled. If MAIN.EXE is out of date (or does not exist),
links the resulting objects to produce MAIN.EXE.

clip main mod1 mod2 mod3 -tfLw
Same as the previous example, but links MAIN.EXE (using
WarpLink) without regard for whether any modules were
recompiled.

3.4. Option Precedence

Clip can get its options from a number of sources: the command
line, a command file (next section), the $Clip: string inside a
source file (next chapter), or the configuration file. Some of
these options may conflict with others, like "-t" in a command
file with "-t-" on the command line. When that happens, Clip
uses these precedence rules to decide which options to use:

* Options in the $Clip: string always take precedence over any
others.

* Options on the command line have the next-highest
precedence.

* Options in a command file are used next.

* Options in the configuration file have the lowest
precedence.

3.5. Command Files

A Clip command file is a text file containing a list of input
file names and options, just as you might enter them on the
command line. Command files make it easy to handle repetitive
compilation tasks.

To use a command file, give its name to the "clip" command
preceded by a "@" character. The default extension for a command
file is .CMD. As a special case, if you do not specify any input
files on the command line, Clip will look for and read a command
file called CLIP.CMD in the current directory.



- 11 -







Command files are free-form. Options and file names may be given
in any order, just as on the command line. In addition, command
files may contain multiple lines, all of which are treated as if
they were entered as a single (very long) command.

Within a command file, "#" is the comment character. Any text
beginning with a "#" is treated as a comment, up to the end of
the line, and ignored by Clip. "#" is only special at the
beginning of a word, so a "#" embedded within a file name or
option does not mark a comment.

Examples:

clip @project
Reads command file PROJECT.CMD, compiling and linking
whatever files the command file calls for.

clip
Reads command file CLIP.CMD, compiling and linking whatever
files it calls for.

clip -t-
Reads command file CLIP.CMD, but ignores the "-t" switch if
specified in the command file.

Here is a typical command file:

-t # Check timestamps
main mod1 mod2 mod3 # Clipper source files
telepath.lib # Required libraries

3.6. Using Clip Instead Of Make

Since Clip looks for CLIP.CMD if you run it with no options, you
can use it as a simple replacement for "make" by placing the
names of all your source files in CLIP.CMD. Including the "-t"
option in CLIP.CMD lets Clip automatically sense which source
files have changed and rebuild only the necessary modules.

You can always override the CLIP.CMD "-t" option by entering
"-t-" on the command line. This will force Clip to rebuild all
object modules without regard for their timestamps.











- 12 -







4. SOURCE FILE OPTIONS

With Clipper 5.0, it has become harder to keep track of the
options needed to compile individual source files. Particularly,
a module written with the "-n" (no implicit starting procedure)
option in mind may not work if compiled without "-n", or vice
versa. Programs written for 5.0 may compile with the "-w"
(warnings) option, while those ported from Summer '87 will not.
The result, in broad terms, is a mess.

Clip allows you to embed the required options for each Clipper
source file in the file itself. ("Required options" sounds like
a contradiction in terms, but we won't go into that.) When Clip
compiles a .PRG file, it reads the first 24 lines of that file
looking for a string of the form:

$Clip: [options]$

where "[options]" is a list of Clipper compiler options. It uses
those options (in addition to any specified on the "clip" command
line, in the command file, or in the configuration file) to
compile that module.

Normally you would place the $Clip: string in a comment somewhere
in your program header. A typical header might be:

*
* banana.prg
*
* Banana-counting and brown-spots module for National
* Chemical Fruit Co. inventory package.
*
* Copyright 1990 by Frutnagle, Fruitbat, and Welk
* Consulting, Inc.
*
* $Clip: -nvw$
*

Some cautions about the $Clip: string:

* It is case-sensitive. Yes, that again. You must enter it
exactly as shown, with no spaces within the text "$Clip:"
and the first letter in upper case.










- 13 -







* Clip searches the first 24 lines of the source file for the
$Clip: string. The number was arbitrary--small enough that
you'd almost always see the $Clip: string immediately when
you load the file into an editor (and small enough that Clip
does not spend too much time reading the file), but large
enough that you (probably) won't have to rearrange your own
comments to fit it in. We decided NOT to make the number of
lines configurable. A lot of the utility would disappear if
source files would compile correctly with one configuration
but not with another.

* Only these options are legal in the $Clip: string:

-a -b -l -m -n -q -v -w

Note that all of these options are toggles (can be turned on
or off). You may want to disable as well as enable options
in the $Clip: string; for example, if a module will not
compile with "-w", consider including "-w-" in the string.

* The $Clip: string works only in directly-compiled .PRG
files, not in ones included by a .CLP file.































- 14 -







5. CONFIGURATION

Whenever you run Clip, it first looks for and reads its
configuration file. This is a text file; its default name is
CLIP.CFG, but if you rename CLIP.EXE the name of the
configuration file changes as well. Clip looks for this file in
the current directory first, then in the directory containing the
executable (CLIP.EXE or whatever you have renamed it).

The format of the configuration file is similar to that of a
command file. It may contain command-line options and file names
(usually the names of default libraries). In addition, two other
kinds of special directives may appear in a configuration file:
environment variable settings, and compilation commands. These
are explained later.

The configuration file will contain whatever options you want to
be the defaults every time you run Clip. (Normally, this will
include at least a "-L" option to specify a linker. You may also
want to include "-q" and similar options.) It will also contain
the names of libraries you want to link with every executable.
In Summer '87, those will be CLIPPER.LIB and EXTEND.LIB, and may
also include third-party libraries if you use them in EVERY
project. With Clipper 5.0, you do not need to include any of the
standard system libraries in the configuration file, as the
compiler places library search commands directly in the object
files.

5.1. Environment Variable Settings

Clip allows you to set or change DOS environment variables from
within a configuration file. Each environment variable setting
must appear on a line by itself. The syntax is:

!name=value

Example:

!include=c:\clipper5\include

You may include the previous value of the variable (or the value
of another variable) using the same syntax accepted in DOS batch
files: by bracketing the name of the variable in "%" signs.

Example:

!path=c:\clipper5\bin;%path%

If the previous value of INCLUDE were "c:\bin;c:\dos", that
example would have the same effect as:

!path=c:\clipper5\bin;c:\bin;c:\dos

- 15 -







Note that changing environment variables in a Clip configuration
file does NOT have any permanent effect. The changes are in
force only while Clip is running, and the old values are restored
when it terminates.

Now, why would you want to do any of this?

If you want to install both versions ('87 and 5.0) of Clipper on
a single machine, you'll find that the names of various programs
and libraries from one version conflict with the other. You'll
probably choose one version as the default, setting your PATH and
LIB and OBJ environment variable to point to that version's
files. Switching versions then becomes a tedious process,
probably involving batch files to change the variables.

Suppose you have Summer '87 installed for normal use, and 5.0
installed in a directory called C:\CLIPPER5. In CLIP5.CFG, you
place these environment variable settings:

!path=c:\clipper5\bin;%path%
!include=c:\clipper5\include
!lib=c:\clipper5\lib

Now whenever you run CLIP5.EXE it will automatically set the DOS
PATH to look for executables in C:\CLIPPER5\BIN. CLIPPER.EXE
will find its header (.CH) files in C:\CLIPPER5\INCLUDE, and the
linker will look for libraries in C:\CLIPPER5\LIB.

5.2. Compilation Commands

The last special feature of the configuration file lets you
change the commands used to compile various kinds of source
files. This is not particularly useful if you program only in
Clipper, but is useful if you sometimes include C or assembly
language modules in your programs.

NOTE: If you don't use C or assembly language, don't bother to
read this. It doesn't affect you.

Compilation commands tell Clip how to handle source files with
each of the four different extensions it recognizes. The syntax
for a compilation command is:

.ext command [parameters]...

where "ext" is one of: "prg", "clp", "c", or "asm". For example,
the normal compilation command line for .PRG files is:

.prg clipper %i %-




- 16 -







Okay, that's still pretty mysterious. This tells Clip that, to
compile a .PRG file, it should run a program called "clipper".
The remainder of the line tells Clip what parameters to pass to
the compiler. The "%" signs mark special strings that Clip will
replace with file names or compiler options. There are three of
these special strings:

%i Replaced by the full name of the source file (including
drive and path, if specified, and extension).

%- Replaced by a list of compiler options, each option preceded
by a "-".

%/ Replaced by a list of compiler options, like "%-" except
that each option is preceded by a "/".

In addition, "%" followed by any other character is replaced by
that other character--so you can use "%%" to put a single "%" in
a compilation command.

The point of all this is to make it possible to change the
commands used to compile C and assembly source files. The
standard configuration files supplied with Clip are set up to use
Microsoft C and Microsoft MASM, with these commands:

.c cl -c -AL -FPa -Gs -Zl %- %i
.asm masm %/ %i;

You might want to change these in several ways. With Microsoft
C, to compile using maximum optimization use:

.c cl -c -AL -FPa -Ox -Zl %- %i

To compile with Turbo C, use (something like):

.c tcc -c -ml -N- %- %i

To use Turbo Assembler for .ASM files, use:

.asm tasm %/ %i













- 17 -


 December 21, 2017  Add comments

Leave a Reply