Electronic Mail
Message #7569854
Date: Tuesday, February 03, 1998   8:27:30 AM
From: IN:perry@moe.acad.humberc.on.ca
To: GRDJ0002
Topic: <none>

Received: from moe.acad.humberc.on.ca [142.214.100.29] by hcol.humberc.on.ca with smtp
        id $T206556 ; Tue, 3 Feb 1998 08:27:10 -0500
Received: by moe.acad.humberc.on.ca (AIX 4.1/UCB 5.64/4.03)
          id AA26566; Tue, 3 Feb 1998 08:27:01 -0500
Date: Tue, 3 Feb 1998 08:27:01 -0500
From: perry@moe.acad.humberc.on.ca (Brian Perry)
Message-Id: <9802031327.AA26566@moe.acad.humberc.on.ca>
To: amalik5225@aol.com, andrewj@rogers.wave.ca, birw5307@hcol.humberc.on.ca,
        bonnie.coursolle@sympatico.ca, bovv0251@admin.humberc.on.ca,
        bsbp0000@moe.acad.humberc.on.ca, calvinlu@idirect.com,
        cand8195@moe.acad.humberc.on.ca, casa2283@moe.acad.humberc.on.ca,
        cius5781@pop.humberc.on.ca, crsc0001@moe.acad.humberc.on.ca,
        cyberlands@ica.net, cyrj1043@moe.acad.humberc.on.ca,
        danno@hcol.humberc.on.ca, fdcg0000@moe.acad.humberc.on.ca,
        frsf0002@pop.humberc.on.ca, grdj0002@hcol.humberc.on.ca,
        hnht0000@pop.humberc.on.ca, jardan@ican.net,
        jdlm0000@pop.humberc.on.ca, kals5385@pop.humberc.on.ca,
        kilw8379@pop.humberc.on.ca, lcxx0000@moe.acad.humberc.on.ca,
        lmmd0000@moe.acad.humberc.on.ca, lrbx0000@pop.humberc.on.ca,
        mala6669@moe.acad.humberc.on.ca, mala6669@hcol.humberc.on.ca,
        mlmv0000@pop.humberc.on.ca, mnhm0000@moe.acad.humberc.on.ca,
        mps@ica.net, mrkm0002@pop.humberc.on.ca, ndrm0003@pop.humberc.on.ca,
        nwlc0000@pop.humberc.on.ca, owtm2393@pop.humberc.on.ca,
        para7881@moe.acad.humberc.on.ca, paulbusby@msn.com,
        perry@moe.acad.humberc.on.ca, prom8329@pop.humberc.on.ca,
        rsnj0001@pop.humberc.on.ca, segm8961@moe.acad.humberc.on.ca,
        sins4731@pop.humberc.on.ca, smokey@better.net, sports@octonline.com,
        stantalo@hotmail.com, tans8855@moe.acad.humberc.on.ca,
        tayr6981@pop.humberc.on.ca, teng1@idirect.com,
        trnb0002@hcol.humberc.on.ca, tvrt0001@pop.humberc.on.ca,
        uy0m9119@pop.humberc.on.ca, vanv7857@moe.acad.humberc.on.ca,
        vivian@tap.net, vrbn9373@pop.humberc.on.ca,
        vrcj0000@hcol.humberc.on.ca, wddm0001@pop.humberc.on.ca,
        whah2965@pop.humberc.on.ca

These are some notes on compiling.  There are about eight pages, so you may
want to print them first.  Towards the end, there are some step-by-step
instructions for each of the environments we use at Humber.

=========================

When most people use the word COMPILE they usually mean the
processing of program source code to convert it into executable code (native
machine language).  That much may seem obvious, but technically it is
wrong!   Modern "compilers", by default, use two separate processes
COMPILE and LINK to achieve that result.  It is possible to do each of
these processes separately, but usually some special action is necessary if
both are not to be done.  Hence the confusion over the meaning of the word
compile.

The COMPILE process translates the source code into machine code, but
cannot make a complete, executable program because various parts of the
program have yet to be supplied either from a library or from the results of
other compiles.  The translated machine code files are called "object files"
and given the filename suffix .OBJ (.o in Unix).  In addition to the machine
code each object file contains two lists which are intended as input to the
link process.  The first list contains the names of all functions whose
definitions are contained within the .OBJ file.  The second list contains the
names of all functions which are referred to (called by) the code in the .OBJ
file, but not defined there (in other words those whose definitions are
contained either in other object files or a library).

The LINK process does whatever is necessary to connect all the object files,
including the those from the standard library and builds the executable.  That
is to say, it reviews the lists of what functions are defined in each of the
.OBJ files against the list of all the functions that are called and matches
them.  If, after that, there are any functions that are needed but which have
not been found then it searches the library for them.  If it finds everything it
needs then it build the executable.  If not it issues a Linker Error message
(or several) listing what functions it cannot find.

In the DOS/WINDOWS environment the name of the executable is taken
from the name of the project if there is one, or the name of the one-and-only
source file and adds the suffix .EXE.  In Unix the name of the executable is
usually supplied by the user.  There is no standard suffix.  If no name is
supplied then the executable is named a.out.  It is possible to create
executables that are not in themselves complete programs (for example,
DOS Overlays (.OVL) or Windows  Dynamic Load Modules (.DLL files),
but these are not discussed on these courses.

From now on, I shall follow common usage and use the word COMPILE to
mean BOTH compile and link, to produce an  .EXE executable unless
otherwise noted.

When most programmers first learn to use C programming language the
programs they first write are small.  Typically, the whole program, except
for standard library functions, is all in one source file.  In the DOS/Windows
environment, the default settings made when the compiler software was
installed enable the linker to find the standard libraries and selecting
COMPILE from the menu bar then MAKE is the only action necessary to
produce an executable.  However, after just a few programs the new
programmer usually learns to write programs in which some parts of the
program are written separately, each in a separate function and each in a
separate source file.  This is done for several reasons, the most important of
which are; because it has been found to be the only way to successfully
write large programs, because it enables functions to be re-used in  more
than one program (just like the standard library functions are) and because it
allows each function to be tested separately, before the whole program is
written.

Once a program is divided in that way then the compiler needs to be told
which particular source files are necessary to build an executable program. 
In the Unix environment this is done by listing the source files on the
command line.  In the DOS/Windows environments it is done by making a
PROJECT file.

The primary purpose of the project file is to tell the compiler and the linker
what source files, object files or additional libraries are needed to build an
executable.  Most programmers do not have the need for and do not bother
to use pre-compiled object files or private libraries so this document
assumes that project files contain ONLY program sources.  NOTE that this
means .C or .CPP files (NOT .H files).  The  use of .H files is commented
on below, not because it is related in any way to projects, but because
students often get themselves into serious trouble by mis-understanding this
and WRONGLY putting .H files into the project.

It is also necessary to tell the compiler which type of executable to produce. 
Originally only one type of executable existed so there was no choice, but
modern compilers allow the same source-code to be used on more than one
target environment so there is a choice to be made.  In the Unix environment
this is done by options on the command line, and normally the default is
appropriately set.  In the ISYS290, 291 courses the choice is always DOS
STANDARD EXECUTABLE, although for debugging on BORLAND
Windows-based compilers is useful to use the EASYWIN option, which
basically creates a DOS STANDARD program with no windows
capabilities, except that it will run in a window.

Creating a project file requires slightly different actions in each of the
compilers so the process is discussed under the heading of the compiler-
name.  The purpose of the project file is, however, common to all compilers.

NEVER MIX .C and .CPP files in the same project file or source file list in
Unix.

NEVER PUT .H files in a project file or source file list in Unix.


The following sections deal with "How to submit a compile" in each of
three environments in use at Humber.

UNIX

In the normal Unix environment the compiler is invoked from the shell
command line with a command in the following format:

     cc -o execname file1.c file2.c file3.c ...etc

the -o option specifies the name of the executable, after which the source
files are listed (as many as necessary) 

TURBO C++

Before dealing with the project you may need to set the current directory
using FILE/CHANGE DIRECTORY so that you are working in the
directory that contains your source files.

You should at least check that the target is properly set.  Choose
OPTIONS/APPLICATION and check that DOS STANDARD EXE is set, if
not change to that.

Choose the PROJECT item from the main menu.

Choose OPEN Project

Use the mouse or <TAB> and arrow keys to choose the existing project (if
you have made and saved it previously), or

Enter the name of your new project.  DO NOT CHANGE the .PRJ suffix.
(Better still, just enter the first part of the name, let the software add the
.PRJ).  In particular, if you mistakenly use a .C or .CPP suffix instead of the
.PRJ you will certainly destroy any source file you have with the same
filename as the project.

When you have done that the Project window should open below the source
window.

To add a source file to the project, position the cursor in the project window
and press the <INSERT> key.  The new file will be added before the line
containing the cursor.  The order in which the source files are listed has no
significance except your own convenience.

You should see an "open file" dialog box.  Select the file you wish to add to
the project and either press the <ENTER> key or Click on the ADD button. 
Repeat this until you have added all the files you need, then either use
<TAB> or the mouse to get to the DONE button and either click it or press
the <ENTER> key.

Your project should now be complete.  To compile, select
COMPILE/MAKE.

If you make a mistake and/or wish to delete a file from a project, select the
file in the project window and press the <DEL> key.

To recall the project window at any time either hit <ALT>W then P, or
select WINDOW/LIST ALL/PROJECT.  IF neither of these work, then you
have not got an open project and you must open or create a project as
described above.

BORLAND C++ versions 4.5 and 5.0 (Creating a new project)

Project filenames have the suffix .IDE (NOT .PRJ)

Select Project from the menu bar.  Select NEW project

This will open the Target Expert Window.

Set the path to the disk and directory that contains your source files and
enter/change the name of your project.  Be careful NOT to change the suffix
from .IDE

Leave the Target Name unchanged, it will be set to the same name as your
project name as entered above.

Select the Target Type as APPLICATION [.EXE]

Select the Platform as DOS [STANDARD]

Leave the Target Model setting unchanged

Click the OK button

This should cause the creation the Project Window, showing one target item
[.exe], possibly with the name of one or more source files under it in a
hierarchical diagram.  THESE SOURCE FILE NAMES ARE PURE
GUESSES BY BORLAND and MAY NOT BE RELEVANT.

To delete source files names you do not want in your project position the
mouse on each in turn and hit the <DELETE> key.  Do not delete the target
item [.exe], just the source files.

To add source files to the Project

Position on the target item [.exe] and hit the  <INSERT> key.  This should
bring up a list of .C and .CPP files in your directory (if not, you did not set
the directory correctly in the Target Expert step above.  Position on the
target items [.exe] and hit the <DELETE> key to delete this project and start
again)

Select the source files you need and press OK

Your project file is now complete, to compile select PROJECT/BUILD ALL

To recall the project window, select VIEW/PROJECT

To change the target type select the Target item in the project window and
right-click the mouse then select Target Expert.  This brings up the Target
Expert window.  You may change any of the settings described in the earlier
section.

The DOS STANDARD EXE setting is necessary for a program you intend
to run under MS_DOS or under the Windows NT or Windows 95 MS_DOS
PROMPT.  However, if you intend to DEBUG a DOS program using the
Interactive Development Environment then you must change the compilation
target to EASYWIN as follows.  This will cause the compilation of a DOS
program which has the ability to run in a Window (though it does not itself
"do Windows").  The IDE Debugger is not supported for DOS STANDARD
programs.

To do this, bring up the Target Expert Window as described above.  Change
the target type to EASYWIN [.exe].  Let the software change the other
settings as necessary, do not override them.

The EASYWIN program should now be recompiled as described above. 
When it runs, it will behave like a DOS program, except that it will run in a
Windows 3.x window, NOT in a DOS window.  You may use DEBUG.


#INCLUDE files and PROJECTS

#include files and projects files are NOT related to each other!  However,
students often confuse the two.  This section is intended to remove the
confusion.

I strongly suggest you follow the simple rules about .H files stated below.  

If you get this wrong you will undoubtedly get strange compiler or linker
error messages, the like of which you will not have seen before.  They will
NOT give you any real clue to their cause and you could make things much
worse trying to act upon them.  Indeed, if ever you get incomprehensible
error messages then the first thing you should check is that you have not
included any files not named *.H and that you do not have any files in your
project that are not *.C or *.CPP.  This will not always lead to a solution,
but it often does.  Needless to say, the comments above about .H files only
make sense if you apply some self-control about the naming and contents of
your .H files.  I strongly suggest you use the following rules.

1. NEVER SAVE a file with a  .H suffix UNLESS you intend it to be used
   ONLY for #include in a C or C++ source file

2. NEVER #include any file EXCEPT one which has a .H suffix.     

3. NEVER use a file with a .H suffix for ANY OTHER PURPOSE than
   #include in a C or C++ source file

4. UNTIL you are very comfortable with #include files, use  (#include) files
   with a .H suffix ONLY for declarative code (variable declarations and
   function  prototypes), NOT imperative ("do something") code.

The #include statement is a "compiler directive".  That is to say, it is an
instruction TO THE COMPILER to do something IMMEDIATELY, in the

<<< Continued to next message >>>

