Bcc55-JFE   Tutorial  
 Using the Compiler and Development Environment 

This page presents a tutorial for C++ programmers on the use of the free IDE made up of the Borland C/C++ 5.5 commandline tools, the JFE editor, and the Makegen and Bclean development tools.

As an example, a C++ program composed of several files is compiled, debugged and linked into a DOS executable.

Download a Sample C++ Program

FirstProg is a minimal C++ program.
Download the self-extracting executable  (32 KB).
Extract the executable into its own directory.

The program itself is composed of three source code files:
Student.h a header file which declares a "Student" class.
Student.cpp a file that implements the Student class body.
StudentDrv.cpp a driver file that exercises (tests) the Student class.

There is another file in the directory, FirstProg.wsp, which is a JFE workspace file. It contains the information, used by the JFE editor, that the 2 ".cpp" files are part of the "FirstProg" workspace, or software project.

Start the JFE editor, then open the "FirstProg" workspace (File->Open Workspace).

The two ".cpp" files are loaded and pop up to the screen. A workspace window shows up on the left, and a toolbar containing the C/C++ development tools buttons appears. Examine the ".cpp" files briefly. You may also load (or Open) the header file into the editor if you are curious to see what it looks like.

Using the Development Tools:

Compile1

As you develop program files one by one,  you will need to compile each file and correct its syntax errors. Let's practice doing this:

- Make "Student.cpp" the current file in the editor (if it is not already) by, for example, clicking on its file tab in the toolbars.

- Click on the "compile1" button. This button allows compilation of individual files.
  The output window appears and displays the output of the compiler. One error is displayed.

- Double-click on the error line. The cursor jumps to the corresponding line in the source code.
 The error message says "Statement missing ; ..". The cursor is blinking on the line just after the error.

Fix the error and recompile... Success this time!

Link1

If our program was a very basic program, self-contained in one single file, all we would have to do in order to complete the process would be to click onto the "link1" button. This would generate an executable (".exe" file) in the current directory. We would then be able to run this program by clicking onto the "run" button.

Makefiles

When a project is composed of several files (the general case), the compilation and linking process is usually controlled by a utility called "make".

"make" reads a special file called a "makefile" to determine what source files it needs to compile and link, and what software libraries it needs to use in order to complete the project. 

It is possible to write a makefile manually using an editor like JFE, and this is indeed what most programmers do. However, this requires a fair amount of knowledge, and is tedious.

The make utility distributed by Borland requires a special makefile syntax. You can learn about it by clicking on the "Help" button, and looking for help on "Make" in the "Command-line tools" in the contents.

Writing makefiles manually is only acceptable in industry, where programmers work for weeks if not months-on-end on the same project and do not have therefore to write too many Makefiles.

Makegen

Since you are going to write many small projects, you will need many Makefiles. The "makegen" utility has been created to simplify the work of creating Borland Makefiles.
(Note that commercial "Integrated Development Environments" -IDE for short-, like Borland C++ Builder, include the equivalent of  makegen for the control of software projects.)

- Click on the "makegen" button.
The blue "Options" screen of Makegen appears. We will not dwell further at this stage on the details of the options and of other Makegen screens. You will play with these later. Just press [Enter]. Makegen creates a valid Borland makefile for you.

Makegen builds makefiles with the following defaults:
 - It includes all the ".c" and ".cpp" files in the current directory as part of your project.

 - It also assumes that the name of the executable is to be the name of the source file that contains the "main()" function (or "WinMain()", etc.. for Windows programs), and simply replaces the ".c" or ".cpp" extension, with ".exe" to obtain the name of the executable.

- It assumes that you want to compile a DOS console application rather than a Windows program.

- It places all the output files into the current directory.

- It links the produced executable with the static libraries, rather than the dynamic libraries.

- It writes a makefile called "makefile.b" into the current directory.

Note:
- These assumptions will be valid for most of your curriculum projects.
In the large majority of cases, after "makegen" finishes, you will immediately be able to build your project by clicking on the "make" button.

- If you are not happy with the makefile produced, makegen allows you to modify these defaults (for example to remove some source files from the project, or to rename the executable produced). Makegen stores your chosen project configuration into a project configuration file "Project.gen" in the current directory. The next time you open Makegen in this directory Makegen will retrieve the saved configuration.

Alternatively, you could directly edit the makefile "Makefile.b" produced by makegen... good luck!

You can call "Makegen /?" at a DOS prompt to view some brief help about what Makegen does.

BTW: The C++ source code for "makegen" is public domain. It has been written with Bcc55.
If you want to adapt makegen to your purposes (modify the defaults, or generate makefiles for other compilers), you are welcome to it. Grab it here.

Make

We now have a working makefile. All we need to do is call "make" to compile and link all the source files in the project with a single click.

- Click on the "make" button...
Oops! another syntax error, this time in "StudentDrv.cpp": obtainMarks is not a member of Student...

This means that "obtainMarks" must be spelt differently in the Student class declaration in the header file. Open "Student.h", check the spelling, and fix the error in "StudentDrv.cpp".

Note: You can make "student.h" part of your JFE workspace, so that the file will be loaded automatically the next time you open the workspace.
You do this by right-clicking onto the "Student.h" name in the workspace window, then selecting "Add file to the project".

-Click on "make" again...Compile...Link...SUCCESS!!

Run / DOS

We now have an executable in the current directory. We can execute it by clicking on "run" when the file that contains the "main()" function is in focus.
-Click on "run" now.

Note: If your program does not run now, go to the section on JFE Workspaces, and read the section on "Transferring Workspaces between Operating Systems". If this is not the cause, skip further down this section and read the "Note" about programs "blinking" on-then-off.

- The program asks for the name of a student...
      Enter it. (anything)
- The program asks for the ID of a student...
      Enter it. (anything)
- The program asks for the student's result...
      Enter any number.

Oops! at this point the program disappears, and we cannot see the final output.

After fixing the syntax problems we must now fix the logic errors of our program. This is a normal part of the development process:

Go to the main() function of the StudentDrv.cpp file (Notice how you can go there quickly by expanding the "studentDrv.cpp" icon by clicking on the little "+" sign, then selecting "main" in the workspace window).

We can see that there is a pause() function call at the end of the program. Why doesn't it work?..
I'll give you the answer:

"Pause normally waits for the next [Enter] key being pressed. However the last thing we did (entering the number for the student's results) left a carriage return -the character for the [Enter] key- into the keyboard buffer (keyboard memory), waiting to be taken. Pause() sees this carriage return and takes it. Therefore there is no pause.

We have to flush that carriage return from the keyboard buffer before pause() has a chance to take it.
Go to the "Student::obtainMark()" function in Student.cpp (..go-on, this time use the quick way, via the workspace window.).
The last line there: cin >> results; is the guilty party. It reads the number, then leaves the carriage-return in the buffer.
To flush that carriage return out of there, add another line just after this:
          cin.ignore();

Now click on "make" again...
Make the file containing  main() -StudentDrv.cpp- the current one on the screen...
Click on "run"... At last everything runs fine!

In the future, remember to always have "cin.ignore()" after reading in a number with "cin >> number".

Note:
- If one of your programs just blinks on the screen and disappears, it could be because of a few things:
1) You are calling "run" with a file other than the one containing "main()" in focus on the screen.
     fix: Change focus to the file containing main() and call "run" again.
2) There is no code to pause at the end of your program.
    fix: Add such code (As an example, see the pause() function in StudentDrv.cpp).
3) Your program is crashing for some internal reason.
     fix: Debug your program.

Alternatively you may want to run your program directly from a DOS console. The console does not disappear after the program exits. This may be handy if your program dies without trace and you want to have some clue as to why this happens. To do this:

- Click on "DOS"

In the MSDOS console that appears, enter the name of your executable (e.g. "studentdrv"). The console will not disappear when your program finishes, so you can always see the final output.


Clean

- Click on "DOS" and enter "dir" to look up the files in the current directory.

We started with 4 files. Now look at all this garbage!
There are:
-  ".obj" files, which are the output of the compilation of each ".cpp" files,
-  "StudentDrv.exe", our executable.
-  "Project.gen" and "Makefile.b" produced by makegen.
- ".bak" and ".org" files produced by JFE for each file edited.
- ".ilc", ".ild", ".ilf", "ils", ".tds" files produced by the compiler and linker.

Some of these temporary files are not small. You cannot afford to keep all this.. its confusing, and you would soon fill-up your hard disk. When you have finished with a project, get rid of all the unwanted junk by pressing "clean".
The "clean" button calls a special utility called "Bclean". A blue "Bclean" screen appears, press [Enter]. This removes all of the files above, except "Project.gen" and "Makefile.b" which may be needed later to recompile and re-link the executable, and the editor temporary files that you may need to retrieve the last version of your program.

You can get some brief help on how Bclean works by calling "Bclean /?" at the DOS prompt.

Note that Bclean is called in interactive mode by the "clean"  editor button. This allows you to prevent deletion of files with a particular extension (the 3 letters after the '.' in the file name) if you wish.

Just before handing in an assignment you may want to clean up your directory of all except perhaps the source code, the executable (.exe) file, the workspace file (.wsp) and your project file and Makefile. In order to do this, go to the DOS screen by clicking on the "DOS" button, and call Bclean in interactive mode:
"Bclean -i".

Bclean in non-interactive mode (just call "Bclean") also does a good job of removing unwanted files.You only need to use the interactive mode if you want to rescue some types of files from deletion.

BTW: The C++ source code for "Bclean" is public domain. It has been written with Bcc55.
If you want to adapt makegen to your purposes (modify the defaults, or generate makefiles for other compilers), you are welcome to it. Grab it here.

Help

- The JFE " ? " button offers help only on JFE.

- The "Help" tools button offers help on the C language, the C++ language, and the Borland development tools. Since this help is designed for Borland C++ Builder, rather than Bcc55, a small section of it is not relevant to this system (the QuickStart Tutorial). Most of it is relevant, though, and you will find the C and C++ language help highly valuable.

There is some extra help which is more rarely needed and is not accessible via the help button:

If some day you receive a compiler or linker error message that you do not comprehend, go to the C:\Apps\Bcc55JFE\Help directory with Explorer and double-click on the "Bcb5errs.hlp" file. You may find the further explanations there useful.


JFE Workspaces

- JFE can save the state of your work on a project into a "workspace" file (ending with extension ".wsp") in the current directory.
This file contains information on what files are in the project, where was the cursor at the time of the last edit, where were the bookmarks, what tools (the buttons) were available, etc...
For multi-file projects, workspaces are essential labour-saving devices. You should create one for any program that contains more than one ".cpp" file.


Creating a Workspace:
When you begin a project in a new directory, you create a workspace for your project by clicking on File->Save Workspace, whenever you have a file opened in the editor. Make sure that you save the workspace file into your project directory, otherwise many things will go wrong.


Workspace Window:
You can see what files are included within your workspace by clicking on view->C/C++-function list. This opens a workspace window to the left of the screen.
All open files, whether part of the project or not, are visible there. If you right-click on the name of a file, you can alternatively "Add it to the project" or "Remove it from the project".


Transferring Workspaces Between Computers:
You can transfer workspace files between computers together with the other files in the project directory without any problem (if both computers use the same Win32 operating systems).
Just load the transferred workspace into JFE on the new computer and everything will work as on the original machine.

Transferring Workspaces Between Operating Systems:
Transferring workspace files between computers running different Win32 systems is almost as troublefree. However if you move a project from Windows 98/95, say, to Windows NT or 2000, then you need to make a slight change for the [Run] and [DOS] buttons to work.

Right-click on the [DOS] button... This opens up the "Application start settings" dialog.
 The application name under Windows 98/95 should be "command.com". Under Windows NT or 2000 it should be "cmd". Make the appropriate change to that entry, then click OK.

Right-click on the [Run] button... Apply the same changes.

Modified: August 2001   Maintained by: cutter@codecutter.net