|
DigiBarn Documents: Teach Compile Bind Run for Xerox 8010 Dandelion from Wildflower site
This tutorial will introduce you to the steps involved in turning a newly written source file into a working program. It is purely "how-to"; that is, it will teach you the mechanics of using programming tools, but will not teach you how to actually write programs in Mesa. When you are through with this tutorial, you probably won't be ready to write your first program in the Xerox Development Environment, but you should have a general idea of the steps and tools involved, so that you will be ready to go as soon as you learn about the Mesa language.
Before starting the next lesson, make sure that your Herald window and your Executive are active. You will also need the files ToolFactorialDefs.bcd, ToolFactorialImplA.mesa ToolFactorialImplB.mesa, ToolFactorial.config, Put.bcd, and Heap.bcd on your local disk. Use your File Tool or your Executive to verify that you have these files and that they are on your search path. If you are missing one or more of them, you will need to ask for assistance.
We recommend that you have completed TeachBooting.nsmail before starting this tutorial.
The Mesa compiler does not have a window of its own. Rather, it runs from the Executive, or from a tool called Command Central. Running the Compiler from the Executive is just like running any other tool from the Executive: you just type "compiler foo". You can compile a group of files by separating the names with spaces, as in "compile MyProgram MyOtherProgram Fred". Capitalization of the file name does not matter, and you can abbreviate "compiler" if you like. You don't have to include the .mesa extension when you type the file name.
The Mesa compiler is a six pass compiler. Try compiling ToolFactorialImplA.mesa from the Executive. While the compiler is running, look at your Herald window. A small cube appears during compilation. This cube has one side for each pass of the compiler. As the compiler enters a new pass, the cube turns to show the corresponding face. In the Executive window, the passes are represented by dots following the command. When errors are found, the number of dots tells you the number of the pass during which the errors were found.
In this case, the compilation will be successful, and you will see a message that gives the number of lines of code, and the number of seconds that the compilation took. When there are errors, you will see how many errors there were, and how long the compiler ran until it encountered them. To see the full compiler log (i.e., any error messages), you will have to load the file compiler.log into an Empty window.
The output of the compiler is a file called ToolFactorialImplA.bcd.
You will often run the Compiler from Command Central instead of from the Executive. Command Central is a tool specifically designed to simplify the processes of compiling, binding, and running a program. Bring up Command Central on your screen. (You may have to run CommandCentral.bcd from the Executive if you can't find the CommandCentral window on your screen.) The command subwindow has both a Compile! command and a Compile: field. To compile a file (or files) from Command Central, just fill in the name of the file(s) to be compiled in the Compile: field, and invoke Compile!. Compile ToolFactorialImplB.mesa. (You don't have to include the .mesa extension.)
When the compilation has finished, the complete log file will be displayed in the bottom subwindow of the Command Central window. For your convenience, this file is automatically loaded into the Command Central text subwindow when the Compiler has finished.
When you compile from Command Central, the cube will appear in the Herald Window just as it did when you compiled from the Executive. Other information, such as the number of passes completed, and the code size (for successful compilations) will appear in the message subwindow of the Command Central window.
There are a number of compiler switches that allow you to specify details of compiler operation. For example, the /b switch tells the Compiler to turn on bounds checking; /e tells it to include error messages; /u to give warnings about uninitialized variables. The complete list of compiler switches and their default values is in the Compiler chapter of your XDE User's Guide. You can set default compiler switches in your user.cm file. The entry CompilerSwitches: can be placed in either your [Executive] section or your [CommandCentral] section, or both. (If you do not have a section for these tools in your user.cm, you can add one.) For now, we suggest that you set your switches to beu-j (the j switch activates cross jumping; a - preceding a switch turns it off). As with other tools, you can override the default values in your user.cm if you like. To specify a different set of switches when running the Compiler from the Executive, just type the list of switches (preceded by a /) on the command line. Compiler switches take the same form as other Executive switches: that is, they can be either global or local. For example, to turn off bounds checking and uninitialized variable checking, you would use the command "Compile/-b-u Myprogram" (global switches) or, equivalently, "Compile MyProgram/-b-u" (local switches). To set compiler switches in Command Central, just invoke Options! to bring up the options window, and edit the switches that are listed under Compiler Switches:. These switches will override the settings in your user.cm; they will be reset to the default user.cm values each time that you deactivate and reactivate the tool (and each time you boot your system).
Compiling a program generates an executable object file (if there are no errors). However, in most cases you will not immediately run the object files generated by the compiler. Instead, you will usually want to use the Binder.
The Binder is a tool that groups individual object files together into a single large object file. (The Binder is thus similar to a linker.) Both the Compiler and the Binder produce object files; the Compiler produces simple object files from source files, and the Binder produces complex object files from simple ones.
For example, if you want to use procedures or types that are found in another module, you will need to use the Binder to associate your files with the files from which you would like to use symbols. The Binder also allows you to group files together in a specific order, so that you can load a single file instead of a large group of files.
The Binder takes as input a file with the extension .config (short for configuration). A .config file is essentially a list of individual object files that you want to group together. You will have to wait until you take the Mesa Course or until you attend a lecture on the Mesa language before you are ready to write a .config file; for now, you will just have to settle for knowing what to do with a config file once you have one.
Running the Binder is much like running the Compiler. To use the Binder from the Executive window, just type "bind foo". You don't need to include the .config extension; this will be assumed. Similarly, to run the Binder from Command Central, fill in the name of the file in the Bind: field, and invoke the Bind! command. Bind ToolFactorial.config now, either from the Executive or from Command Central. This will produce an object file called ToolFactorial.bcd.
The file binder.log contains the log file for the most recent binder command. This file is automatically loaded into the Command Central text subwindow (as was compiler.log); if you bind from the Executive, you will have to load it manually.
You can also set Binder switches, just as you did for the Compiler. The default Binder switches are set in your user.cm file; the complete list of available switches can be found in the Binder chapter of your XDE User's Guide.
Since the Compiler and the Binder both produce files with the .bcd extension, it is important for all of the modules that make up a program to have distinct root names. For example, if you compiled a file called ToolFactorial.mesa, you would then have a file called ToolFactorial.bcd. If you then tried to bind a file called ToolFactorial.config, you would run into trouble, because the binder would try to create a file called ToolFactorial.bcd and it would find that such a file already existed. Depending on which files conflict, the Binder may give you an error message or it may just overwrite the earlier file.
The best way to avoid mistakes is to adopt a consistent naming convention. You should make sure that all .mesa and .config files have distinct root names. Thus, program modules that implement a particular interface should be named MumbleImpl.mesa, or MumbleImplA.mesa and MumbleImplB.mesa when there are multiple implementation files.
You also need to be sure that you include the extension (.mesa or .config) when you name a file.
Once you have an object file, either a simple one produced by the Compiler or a more complex one produced by the Binder, you are ready to run it and see if it works. Surprisingly enough, this step is probably the one in which the Xerox Development Environment differs most from the systems that you are accustomed to. The philosophy of the Xerox Development Environment is that programs should be written, compiled, and debugged in a separate logical volume from where you run them.
In the XDE, the word "volume" can mean either a physical volume or a logical volume. A physical volume corresponds to a storage device, typically your hard disk. A logical volume is usually a subset of a physical volume; there are usually several logical volumes on a single physical volume. (However, a large logical volume could span several physical volumes. There can be no more than 10 logical volumes on a particular physical volume.) Each logical volume is largely protected from actions in other logical volumes. Thus, having a separate logical volume for running your test programs ensures that they have a fresh and clear test area in which to run.
This is called the "world-swap" approach to debugging. When you are ready to run a test program, you start from a "debugger" volume (the one in which you wrote and compiled your program.) Before a test program can be run, the object version must be copied to the test volume, the current contents of real memory must be swapped out and written to a file, and finally the test volume booted (replacing the contents of real memory). This is called a "world swap" to the client volume. When you are done testing your program in the client volume, you can "world swap" back to the debugger via a similar process.
We discuss world swapping in greater detail in debugger.nsmail, so you don't need to worry about it too much now. For now, you just need to be familiar with the theory that you will be executing your programs in an entirely different logical volume from where you develop them.
The name of the volume in which you will be running your test programs is Tajo. Some machines will have a Tajo volume; other machines will have the Tajo boot file stored on the another volume. The first thing that you should do is find out which way your machine is set up. To find this out, Chord in the Herald window and bring up the Boot From: menu. If Tajo is listed on this menu, then Tajo is the name of your test volume. Otherwise, the Tajo boot file is on another volume. Don't boot either volume now; just figure out the anme of the volume on which your Tajo boot file is stored..
The rest of this tutorial refers to the test volume as Tajo, but you should substitute another volume name if appropriate. You should also edit your user.cm file to include the information about which way your machine is set up. Load your user.cm into a file window, and find the [Executive] section. Make sure that there is a ClientVolume: entry there; it should have the name of the volume where your Tajo boot file is stored.
(If your user.cm file is wrong, the changes you make will not take effect until you next boot. If you need to change your ClientVolume: entry on the short term (without booting), you can just edit the ClientVolume: entry in the Command Central options window.)
You will be running your programs in Tajo, but the object file that you want to run is on the CoPilot volume. Thus, you will have to copy the object file from CoPilot to Tajo, and then boot Tajo, and finally run the program from the Tajo Executive. If you have never booted Tajo, you will have to do so before you can run a program. (Boot Tajo from the Herald Window of your CoPilot volume, wait until you reach Tajo, then press SHIFT-STOP together to return to CoPilot.)
There are two ways to accomplish these steps: an easy way, and a hard way. In this lesson, you will learn the hard way; that is, you will perform all of the steps manually. You will rarely have to do this process manually, but it is important that you do it at least once so that you understand exactly what is happening. The next lesson covers the easy way.
Type "open tajo/w" (or "open user/w") in your Executive. The /w switch specifies that the volume is being opened for writing.
Now copy the file onto the Tajo volume, with the Executive command line "Copy Now that you have stored the file onto Tajo, you just have to get there and run the file. When you reach Tajo, you will need to load and run the file ToolFactorial from the Tajo Executive. This program creates a tool window, with three fields in its form subwindow: Number=, Format: and CalculateFactorial!. The number field is used to specify the input to the command; format is used to specify the format (base) of the answer, and CalculateFactorial! actually performs the command. You can experiment with this test program if you like. (The input must be between 1 and 12.)
Remember: When you are through running the test program, you can return to CoPilot by pressing SHIFT-STOP.
Boot Tajo from the Herald window Boot from: menu now. Remember to run ToolFactorial from the Executive window when you get there.
The easy way to run a program is via Command Central. To run a program from Command Central, all you have to do is fill in the name of the program in the Run: field, and invoke the Run! command. When you invoke Run!, the object file is copied to the Tajo volume, Tajo is booted, and finally the program is loaded from the Tajo Executive. Try filling in ToolFactorial in the Run: field and then invoking the Run! command, if you like.
There are also switches that you can specify in the Run: field. For example, if you enter filename/d in this field, the debugger will be called immediately after the tool is loaded (so that you can set breakpoints, or look at the state of things). There are several other switches that can appear here; check the Command Central chapter of your XDE User's Guide for a full list.
In general, you should always run test programs in the Tajo volume, either from CommandCentral or by copying them over manually.
You have now had a chance to compile, bind, and run a program in the Xerox Development Environment. The easy way to sequence these three steps is with Command Central's Go! command.
The Go! command invokes the Compile!, Bind! and Run! commands sequentially. Thus, if you fill in the name of a file or the Compile: field, the Bind: field, and the Run: field, and then invoke Go!, you will not have to do anything else until you end up in Tajo. Of course, if the compiler or the binder finds errors, the other commands will not be invoked. Thus, for example, if the compilation is not successful, the Go! command will abort after the compilation, and neither Bind! nor Run! will be invoked.
You now know how to compile, bind, and run a test program in the Xerox Development
Environment. However, there's a catch to all this. As you know, no test program
really runs perfectly the first time. So, to prepare you for the first time
you really test a program, you should work through the next tutorial, called
TeachDebugger.nsmail.
See Also:
Back to Wildflower site
Please
send site comments to
our Webmaster.
The Digibarn's extensive collection of Xerox computers and other artifacts
Please see our notices
about the content of this site and its usage.
(cc) 1998- Digibarn Computer Museum,
some rights reserved under this Creative Commons license.