INTRODUCTION.

cMent(*) is a Rexx program which eliminates the need for complex
development environments like IBM's Workframe and Nmake.  It is
designed to allow you to use your favorite editor, your favorite
compilers and your favorite debugger, with the Workplace Shell
itself as your integrated development environment.

First, you create a project folder (directory) containing all of
your source files, "associated" with the program object for your
favorite OS/2 or DOS editor.  You can then start as many editing
sessions as you like, just by double-clicking on the source file
objects in the project folder.  Switching between these windows
and the project folder is fast and easy with Alt-Esc, Ctrl-Esc
and/or the mouse.  You don't even have to close the editor if you
want to compile and link.

When you're done with your changes, Alt-Esc to the project folder
and right click on an empty area of the folder.  From the pop-up
menu select "Build old", "Build all" or "Build optimized" and the
cMent program does the rest.  You don't even need to create a
make file, because cMent handles all of the common dependencies
completely automatically.  Based on standard file extensions,
cMent runs pre-processors; compiles resources; compiles and/or
assembles source to .OBJ or .W files; link edits to .EXE or .DLL
or .DRV; adds your resources; and builds an import library for
your .DLL.  It even correctly handles the C/set++ intermediate
code linker.

All of this takes place in the background, while you get on with
something else.  And after your project has been built, the cMent
"project.log" file automagically reappears in the project folder.
You can view the log with your editor, and then test your program
with a quick double-click on a debug program object.  The only
thing you can't yet do is position your editor from the compiler
error messages (this feature is currently under development).

Its all very simple and takes only an hour or so to install and
tailor to your needs.  Makes you wonder why compiler vendors all
have to stick you with their own brand of completely different
and usually over-engineered "integrated development environment".
They don't seem to care about your lost productivity every time
you have to learn a new interface, or perhaps they just want to
discourage you from switching to a competitor's product.

Well, not any more.  You already know how to use cMent because it
runs in the OS/2 Workplace Shell and it's controlled by standard
DOS/OS2 SET commands (or Rexx if you want to get really clever).
It uses your own favorite editor and it comes already tailored
for C/Set++ and MASM.  It can be easily tailored to OS/2 and DOS
compilers from Borland, IBM, Watcom, GNU, Microsoft, and just
about everybody else.  From now on, its probably the only project
builder you'll ever need.





(*) cMent is a trademark of The Masterpiece Software Company.
INSTALLATION PROCEDURES.

Mixing cMent is almost as easy as pouring it.  First, copy all of
the .CMD files to a directory in your PATH (you might want to
create a new directory, to make things easier if you later apply
any fixes).  The distributed files are as follows:

     cMent.cmd      The main program launcher, for "Build old";
     cMentAll.cmd   Launches cMent.cmd for a "Build all";
     cMentOpt.cmd   Launches cMent.cmd for a "Build optimized";

     cMentor.cmd    The main (background) project builder;

     cMentSet.cmd   Sample control file, to be modified by you;

     rc2res.cmd     Compiles .RC files to .RES;
     usa2res.cmd    Compiles .USA (or other) files to .RES;
     asm2obj.cmd    Assembles .ASM files to .OBJ;
     c2obj.cmd      Compiles .C to .OBJ;
     c2w.cmd        Compiles .C to .W (for intermediate linker);
     cpp2obj.cmd    Compiles .CPP to .OBJ;
     cpp2w.cmd      Compiles .CPP to .W (intermediate linker);
     ccc2exe.cmd    Compiles .CCC directly to .EXE (ANSI C);
     cxx2exe.cmd    Compiles .CXX directly to .EXE (C++);

     cMentWal.cmd   Displays logo screen while starting;


As you can see, the xxx2xxx files do the actual work of program
translation.  They are called by cMentor.cmd when it detects a
target which needs to be rebuilt (usually because it's outdated).
In principle, you CAN modify these files to tailor them to your
needs, but you'll probably find it easier just to change the name
and options for the program in the cMentSet.cmd file.  We'll show
you how to do this in a moment.  We'll also discuss how to create
your own files for other languages (e.g. pas2exe or pli2obj).
But for the moment, leave these files as they are.

The next step is to add the "build" options to the pop-up menus
of your project folders.  Right click to the pop-up menu and then
"open" the "settings" notebook.  Now select the "menu" tab.  Make
sure the "primary pop-up menu" is highlighted in the top part of
the window and then, in the lower part of the window, select the
"create another" button to add each item to the menu.  For "Menu
item name" you enter "~Build old" and for "program name" enter
"cMent.cmd".  Now "create another" item for "Build a~ll" with
"cMentAll.cmd" and for "Build optimi~zed" with "cMentOpt.cmd".
(The tilde characters cause the next character to be underlined
in the menu, and therefore allow you to select the appropriate
build option just by pressing "B", "L" or "Z" from the folder's
pop-up menu).  Close the settings notebook when you're finished.

Unfortunately, you'll have to repeat this process for all of your
existing projects (unless you yell really loud and make me write
a program for it).  For your new projects, however, it will be
much easier if you create a folder template.  Personally, I use a
work-area folder called "opus" for all my current projects.  In
this, I keep my active project folders, templates for new source
files of different types and the template for new projects.  The
build items are preset for this template, and the folder itself
also contains a debug program object and some other stuff which I
find useful in every project.  All of this gets copied whenever I
create a new project.


TAILORING WITH THE CONTROL FILE.

If your system is exactly the same as mine, you can now start the
fun part of building projects.  However, since your directory
paths and compiler options are probably completely different from
my own, its probably a good idea if you first tailor cMent to fit
your needs.  At the global level, this is done entirely with a
single control file called "cMentSet.cmd".  This is actually just
a very simple batch file which is called by cMentor before the
build itself is started.  It will help you understand this dis-
cussion better if you print a copy of the file for reference.

The first two lines set global options for LINK386 and ICC (the
IBM C/Set++ compiler).  Modify them as you see fit, but note that
if you are compiling both C and C++ source code, only options
common to both languages should be included in the ICC variable.
Individual language options can be specified with the program
execution variables, as described below.

The next two lines set the system PATH variable to include all of
your compilers and tools, and also set the TMP variable which is
required for C/Set++.  Note that TMP is also required for cMent
itself, since this is used to specify the directory where the
temporary work files will be placed.

The INCLUDE and LIB variables on the next two lines are pretty
much self-explanatory to an experienced programmer like yourself.

The SOURCE list specifies the extensions of all your source file
types.  Extensions which are NOT in this list will NOT be consid-
ered for pre-processing or for compilation to .OBJ or .W files.
So, if you intend to add other source file types later, you can
add their extensions now.

The TARGET list specifies all of the translations to be performed
by cMent (with the exception of link editing, which is handled in
a special manner).  Basically, this is a list of the xxx2xxx.cmd
files we saw earlier, except that a given source extension can
only appear once.  In this example, which is set up to work with
the C/Set++ intermediate code linker, c2obj and cpp2obj are both
omitted because we want to compile to .W files.  If you prefer to
use conventional linking, replace c2w with c2obj, and cpp2w with
cpp2obj.  You can also include additional translations by copying
one of the distributed files and naming it "extension2extension"
(for example, "pli2obj').  You will also have to modify the text
of this new file to create a new execution variable (see below).

The ASM variable is used by asm2obj to build the command line for
assembling each of your .asm files.  Essentially, the source file
name is concatenated to ASM and the resulting command is executed
by cMent.  If you are using Borland's assembler, just change the
program name to TASM.EXE.  And, of course, you can change the
options as you see fit.
The C, CPP, CCC and CXX variables are used in exactly the same
way within their respective xxx2xxx commands.  Again you can set
the program name and options as you see fit.  If you create your
own xxx2xxx files, they must have similar variables which should
be set here also.  See any of the xxx2xxx files for an example.

The RC variable is used in like fashion within the rc2res and the
usa2res commands.  The only reason the two source extensions are
different is because I prefer to use .USA files for my standard
resources and other extensions for international versions (which
I compile and add with a separate procedure).  Personally, I do
not use the .rc extension.

The EXE, DLL and DRV variables are used in a similar way by the
internal link edit procedure, after it has determined the type of
target to be produced.  In this example, linking is performed via
ICC (this is pretty much required if you are using C++ templates)
but you can use LINK386 or some other linker if you prefer.

Special note:  You can also specify the paths and names of any
.w, .obj and .lib files which you wish to include in all of your
links (for example to enforce wild-card expansion in your exe
files).  cMent will insert these names at the appropriate point.

The final IF statement is used to toggle into full optimization
for your production builds.  When you select "Build optimized"
from the pop-up menu, the OPT variable is set to "YES" before the
cMent program itself is started.  By testing for this, you can
modify the ICC variable to turn off debugging options and turn on
any required optimizations.

Please note that the distributed cMentSet.cmd is only an example
of the file which YOU must provide (although it includes every-
thing the average C/Set programmer will require).  Since it is a
standard command file, executed from within cMent, you can insert
ANYTHING you want to do before building actually starts.  Also,
you can over-ride the global cMentSet.cmd by placing a file with
the name "project.set" in any individual project directory.  This
is NOT a standard command file, even though it appears to act in
this way.  If present, the lines in this file are INTERPRETED one
by one, AFTER cMentSet has been executed.  Of course, a cMentSet
command within the project directory can be used to replace the
global command entirely.


THE BUILDING CODE.

As with any building project, it helps to understand the rules to
be applied.  The following describes a conditional (Build old) of
a DLL with all the bells and whistles.  This is about the most
complicated example I could think of, and everything else is just
a simpler variation.  A "Build all" or "Build optimized" works in
much the same way, except that all possible targets are built.

1.  PRE-PROCESSING.  cMent identifies all files with a SOURCE
listed extension, for which there is also a TARGET listing with a
target extension OTHER than .w, .obj, .exe, .dll or .drv.  If the
target is older than the source or if any first-level, non-system
INCLUDE file is newer than the source, then the listed xxx2xxx is
executed for that file.  Typically, this step results in modified
.RC (or .USA) files being compiled into .RES files.  However, you
can also include your own pre-processor, if so desired.

2.  TRANSLATION.  This is the main compilation step.  This time,
cMent identifies SOURCE listed files for which the target IS .w
or .obj but still NOT .exe, .dll or .drv.  Again, the compilation
(or assembly) is conditional on the age or absence of the target
and the age of any first-level, non-system INCLUDE file.  This
step typically compiles modified .ASM, .C and .CPP files to .OBJ
or .W files.  Compilation also occurs if the first-level header
files have been modified.

3.  LINK EDITING.  This is the most complicated step performed by
cMent.  Linking is performed ONLY if there is an .EXE, .DLL or
.DRV file with the SAME name as one of the .w or .obj files in
the project folder.  (By implication, this means that the final
executable target must have the same name as one of your .c, .cpp
or .asm files).  In the early stages of development, there won't
be a final target file and thus there won't be any unnecessary,
timewasting attempts at an impossible link.  When you are really
ready to link, simply rename the primary object file to .exe or
.dll or .drv and rebuild.  The now missing object file will be
built again and, from this time hence, linking will be performed
as a normal part of the build process.

If a valid target exists, cMent then builds a list of the .w and
.obj files to be linked.  It also identifies any .def and .res
file with the same name as the target.  Only if one of the object
or .def files is newer than the target is the link actually run.

If a link is actually performed, or if there is a .res file with
a later timestamp than the target, then any identified resources
are added to the executable with the resource compiler.  Finally,
if your target is a .dll, an import library is built for the use
of your calling applications (but only if the .lib file is now
older than the target).

4.  COMPILING DIRECTLY TO .EXE.  This is done as a completely
separate step, after the primary target has been built.  You can
therefore keep one or more test programs in the same folder as
the primary target, provided each test program is coded as a self
contained .ccc or .cxx file.  It is also possible to create a
project folder without any primary target but just a number of
simple, single module programs.  Each .ccc or .cxx file is then
compiled individually but only if there is no matching .exe file;
if the source is newer than the .exe; or if the source is older
than any first-level user header file.

5.  DEBUGGING AND TESTING.  While all of the above is going on,
output from the compilers, linker and other tools is re-directed
to a project.log file in the main project folder.  During the
build itself, which executes as a detached background task, the
attribute of this file is set to "hidden", so that it disappears
from view in the project folder.  After the build is completed,
project.log is unveiled to inform you that review of the log and
program testing can now begin.  This last is best performed with
WPS program objects which you create in the project folder (for
your favorite debugger, or even the target/test program itself).
All in all, I believe that cMent is a far superior approach to
the IDE's provided by compiler vendors.  It allows you to mix and
match all of your favorite tools, it uses the standard OS/2 user
interface with which you are already familiar, and it keeps you
from being locked in to any particular compiler vendor.  Its also
fast, flexible, convenient and dirt cheap!


SHAREWARE DISTRIBUTION POLICY.

Although I am a commercial software developer, I am releasing
cMent version 2.0 as shareware because I do not expect it to ever
become a major revenue producer.  I seek only to receive a small
amount of compensation for my work on a program which I think my
fellow developers will find extremely useful.

On the logo screen you will see a message to the effect that your
$20 registration fee will be used for further development.  This
is not a nag message, but just a simple statement of how your fee
will be spent.  Version 2.1 will include additional support for
C/Set++ 2.1, support for error positioning within most editors,
and probably some other features as well.

You are hereby granted permission to try out cMent for evaluation
purposes only for a period of up to 30 days.  You may also pass
on a copy of the original, unmodified .ZIP file to any person who
understands and supports the shareware concept.  I reserve my own
rights to all derivative works, and you are therefore not allowed
to distribute modified copies of the program to anyone.  Not even
your mother-in-law.

If you wish to continue using cMent you must mail in your fee and
the attached registration form.  (International users please send
a money order or traveller's check).  If you actually read this,
and if your registration is postmarked before January 1994, you
may reduce the fee to $15.  This last on the principle that users
shouldn't have to pay full price for .0 of anything.  Such bold
adventurers should also receive a free copy of .1 and, if you do
register, you will indeed receive the next version by mail.

If I don't get many registrations, then 2.1 will not be released
publically.  There will be a 2.1 but it will go only to those who
have registered.  I'm being honest with you, so please be honest
with me.


eMAIL SUPPORT POLICY.

cMent will be supported exclusively by email to 72650,1533 on the
Compuserve network.  From Internet use 72650.1533@compuserve.com.
I will always support registered users, and I will try to support
unregistered users as well.  However, this latter support might
have to be limited in the future.

                      cMent REGISTRATION FORM
                      =======================


Note: Please mail this form even if you don't wish to register.
Your comments will help me improve the program, perhaps to the
point that you can use it yourself in the future.


Your name:     __________________________________________________

Organization:  __________________________________________________

Address:       __________________________________________________

               __________________________________________________

               __________________________________________________

eMail/phone:   __________________________________________________





Comments, suggested changes or enhancements:

_________________________________________________________________

_________________________________________________________________

_________________________________________________________________

_________________________________________________________________

_________________________________________________________________

_________________________________________________________________

_________________________________________________________________

_________________________________________________________________





Please mail this form with your registration fee to:

                    The Masterpiece Software Company,
                    1 Pronghorn Park, Parks, AZ 86018
                    United States of America.


Thank you for your support.
