ref: e11c7aa718df592bd69de53ce1d6498cc870f256
dir: /doc/dev.ms/
.TL Program Development under Inferno .AU Roger Peppé rog@vitanuova.com .SH Introduction .PP Inferno provides a set of programs that, used in combination, provide a powerful development environment in which to write Limbo programs. .I Limbo (1) is the compiler for the Limbo language; there are versions that run inside and outside the Inferno environment. .I Acme (1) is an integrated window system and editor, and the preferred source-code editing tool within Inferno. The Limbo debugger, .I wm-debug (1), allows interactive inspection of running Limbo programs. .I Stack (1) allows a quick inspection of the execution stack of a currently running process. .SH Getting started .PP This document assumes that you have already managed to install Inferno and have managed to obtain an Inferno window, running the Inferno window manager, .I wm (1). The document \&``Installing Inferno'' in this volume has details on this. If running within emu, it is worth giving Inferno as large a window as possible, as it cannot be resized later. This paper assumes that you are using a three-button mouse, as it is not feasible to use Acme without a three-button mouse. (if you have a two button mouse with a ``mouse wheel'', the wheel can be used as the middle button). The first thing to do is to get Acme going. By clicking on the Vita Nuova logo at the bottom left of the window, you can display a menu naming some preconfigured commands. If this has an ``Acme'' entry, then just clicking on that entry will start acme. If not, then click on the ``Shell'' entry, and type .P1 acme .P2 to start it up. The Acme window should then appear, filling most of the screen (the window manager toolbar should still be visible). .SH Acme basics .PP For a general overview and the rationale behind Acme, see ``Acme: A User Interface for Programmers'', elsewhere in this volume, and for detailed documentation, see .I acme (1). The basics are as follows: .PP Acme windows are text-only and organised into columns. A distinctive feature of Acme is that there are no graphical title bars to windows; instead, each window (and additionally each column, and the whole Acme window itself) has a textual .I tag , which can be edited at will, and is initially primed to contain a few appropriate commands. .PP An Acme command is just represented by text; any textual command word may be executed simply by clicking with the middle mouse button on the word. (See ``Acme mouse commands'', below). If Acme recognizes the word that has been clicked on as one of its internal commands (e.g. Put, Undo), then it will take the appropriate action; otherwise it will run the text as a shell command. (See .I sh (1)). .SH Acme mouse commands .PP Mouse usage within Acme is somewhat more versatile than in most other window systems. Each of the three mouse buttons has its own action, and there are also actions bound to .I chords of mouse buttons (i.e. mouse buttons depressed simultaneously). Mouse buttons are numbered from left (1) to right (3). Button 1 follows similar conventions to other window systems - it selects text; a double click will select a line if at the beginning or end of a line, or match brackets if on a bracket character, or select a word otherwise. Button 2, as mentioned above, executes an Acme command; a single click with button 2 will execute the single word under the click, otherwise the swept text will be executed. Button 3 is a general ``look'' operator; if the text under the click represents a filename, then Acme will open a new window for the file and read it in, otherwise it will search within the current window for the next occurrence of the text. Clicking button 2 or button 3 on some text already selected by button 1 causes the click to refer exactly to the text selected, rather than gathering likely-looking characters from around the click as is the default. .PP There are two mouse chord sequences which are commonly used in Acme (and you will find that some other programs in the system also recognise these sequences, e.g. .I wm-sh (1)). They are both available once some text has been selected by dragging the mouse with button 1, but before the button has been released. At this point, touching button 2 will delete the selected text and save it in Acme's .I snarf buffer; clicking button 3 replaces the selected text with the contents of the snarf buffer. Before button 1 has been released, these two buttons reverse each other's actions, so, for example, selecting some text with button 1, keeping button 1 held down, then clicking button 2 and button 3 in succession, will save the selected text in the snarf buffer while leaving the original intact. The following table summarises the mouse commands in Acme: .KS .TS center box; l l . B1 Select text. B2 Execute text. B3 Open file or search for text. B1-B2 Cut text. B1-B3 Paste text. B2-B3 Cancel the pending B2 action. B3-B2 Cancel the pending B3 action. .TE .ce .I "Acme mouse command summary" .KE .SH Scrolling and resizing Acme windows .PP The scroll bars in Acme are somewhat different from conventional scroll bars (including the scroll bars found in other parts of Inferno). Clicking, or dragging, with button-2 on the scrollbar acts the most like the conventional behaviour, namely that the further down the scroll bar you click, the further down the file you are shown. .PP True to form, however, Acme doesn't omit to make the other buttons useful: button-1 and button-3 move backwards and forwards through the file respectively. The nearer the top of the scrollbar the mouse, the slower the movement. Holding one of these buttons down on the scrollbar will cause the scrolling motion to auto-repeat, so it is easy to scroll gently through the entire file, for instance. .PP The small square at the top left of each Acme window is the handle for resizing the window. Dragging this square from one place to another (within Acme) will move the window to the new place. A single button click in this square will grow the window: button 1 grows it a little bit; button 2 grows it as much as possible without obscuring the other window titles in the column; button 3 grows it so it covers the whole column (all other windows in the column are obscured). .SH Creating a new file .PP All Limbo programs are composed of .I modules and each module is stored in its own file. To write a Limbo program, you need to write at least one module, the Limbo .I "source file" , which will then be compiled into Dis code which can then be run by the Inferno Virtual Machine (VM). The first step is to decide where to store the file. When Acme starts up, it creates a new window containing a list of all the files in the directory in which it was started (usually your home directory). As a consequence of the mouse rules above, a click of button-3 on any of those filenames in that window will open a new window showing that file or, if it is a directory, a list of the files and directories it contains. .PP An important aspect in Acme's mouse commands, is that the command is interpreted .I "relative to the window's current directory", where the current directory is determined from the filename in the window's tag. For instance, Acme commands executed in the tag or body of a window on the file .CW "/usr/joebloggs/myfile.txt" would run in the directory .CW /usr/joebloggs . .PP So, to create a new file in Acme, first open the directory in which to create the file. (If this is your home directory, then it's probably already on the screen; otherwise, you can just type (anywhere) the name of the directory, and button-3 click on it. If the directory does not exist, then no window will be created. Then, within the directory's window or its tag, choose a name, .I filename , for your file (I'll use .CW myprog from here on, for explanatory convenience) , type the text: .P1 New \fIfilename\fP.b .P2 select this text (the Escape key can also be used to highlight text that you have just typed), and button-2 click on it. This should create a new empty window in which you can edit your Limbo source file. It will also create a window giving a warning that the file does not currently exist - you can get rid of this by clicking with button-2 on the text .CW Del in the tag of that window. .SH Editing the source file .PP You can now edit text in the new window. Type in the following program: .P1 implement Myprog; include "sys.m"; sys: Sys; include "draw.m"; Myprog: module { init: fn(nil: ref Draw->Context, argv: list of string); }; init(nil: ref Draw->Context, argv: list of string) { sys = load Sys Sys->PATH; sys->print("Hello, world\en"); } .P2 When typing it in, note that two new commands have appeared in the tag of the new window: .CW Put and .CW Undo . .CW Put saves the file; .CW Undo undoes the last change to the file, and successive executions of .CW Undo will move further back in time. In case you move too far back accidentally, there is also .CW Redo , which redoes a change that you have just undone. Changes in the body of any window in Acme can be undone this way. .PP Click with button-2 on the .CW Put command, and the file is now saved and ready to be compiled. If you have problems at this point (say Acme complains about not being able to write the file), you have probably chosen an inappropriate directory, one in which you do not have write permission, in which to put the file. In this case you can change the name of the file simply by editing its name in the window's tag, and clicking on .CW Put again. .SH Compiling the source file .PP Now, you are in a position to compile the Limbo program. Although you can execute the Limbo compiler directly from the tag of the new file's window, it is usually more convenient to do it from a shell window. To start a shell window, type .CW win '' `` at the right of the tag of the new file's window, select it, and click with button-2 on it. A new window should appear showing a shell prompt (usually .CW "; " '' `` or .CW "% " ''). `` At this, you can type any of the commands mentioned in Section 1 of the Programmer's Manual. Note that, following Acme's usual rule, the shell has started up in the same directory as the new file; typing .P1 lc .P2 at the prompt will show all the files in the directory, including hopefully the newly written Limbo file. .PP Type the following command to the shell: .P1 limbo -g myprog.b .P2 If you typed in the example program correctly, then you'll get a short pause, and then another shell prompt. This indicates a successful compilation (no news is good news), in which case you will now have two new files in the current directory, .CW myprog.sbl and .CW myprog.dis . The .CW -g option to the .CW limbo command directed it to produce the .CW myprog.sbl file, which contains symbolic information relating the source code to the Dis executable file. The .CW myprog.dis file contains the actual executable file. At this point, if you type .CW lc , to get a listing of the files in the current directory, and then click with button-2 on the .CW myprog.dis file, and you should see the output ``Hello, world''. You could also just type .CW myprog at the shell prompt. .PP If you are normal, however, the above compilation probably failed because of some mistyped characters in the source code; and for larger newly created programs, in my experience, this is almost invariably the case. If you got no errors in the above compilation, try changing .CW sys->print to .CW print , saving the file again, and continue with the next section. .SH Finding compilation errors .PP When the Limbo compiler finds errors, it prints the errors, one per line, each one looking something like the following: .P1 myprog.b:13: print is not declared .P2 This shows the filename where the error has occurred, its line number in the file, and a description of the error. Acme's button-3 mouse clicking makes it extremely easy to see where in the source code the error has occurred. Click with button-3 anywhere in the filename on the line of the compilation error, and Acme will automatically take the cursor to the file of that name and highlight the correct line. .PP If there had been no currently appropriate open Acme window representing the file, then a new one would be created, and the appropriate line selected. .PP Edit .CW myprog.b until you have a program that compiles successfully and produces the ``Hello, world'' output. For a program as simple as this, that's all there is to it - you now know the essential stages involved in writing a Limbo program; there's just the small matter of absorbing the Limbo language and familiarising yourself with the libraries (``The Limbo Programming Language'' elsewhere in this volume, and .I intro (2) are the two essential starting points here). .SH Finding run-time errors .PP For larger programs, there is the problem of programs that die unexpectedly with a run-time error. This will happen when, for instance, a Limbo program uses a reference that has not been initialised, or refers to an out-of-bounds array element. .PP When a Limbo program dies with a run-time exception, it does not go away completely, but remains hanging around, dormant, in a .I broken state; the state that it was in when it died may now be examined at leisure. To experiment with this, edit the Myprog module above to delete the line that loads the .CW Sys module .CW "sys = load Sys" ...), ( and recompile the program. .PP This time when you come to run .CW myprog , it will die, printing a message like: .P1 sh: 319 "Myprog":module not loaded .P2 The number .CW 319 is the .I "process id" (or just .I pid ) of the broken process. The command .CW ps , which shows all currently running processes, can be used at this point - you will see a line like this: .P1 319 245 rog broken 64K Myprog .P2 The first number is the pid of the process; the second is the .I "process group" id of the process; the third field gives the owner of the process; the fourth gives its state (broken, in this case); the fifth shows the current size of the process, and the last gives the name of the module that the process is currently running. .PP The .CW stack command can be used to quickly find the line at which the process has broken; type: .P1 stack \fIpid\fP .P2 where .I pid is the number mentioned in the ``module not loaded'' message (319 in this case). It produces something like the following output: .P1 init() myprog.b:12.1, 29 unknown fn() Module /dis/sh.dis PC 1706 .P2 As usual, a quick button-3 click on the .CW myprog.b part of the first line takes you to the appropriate part of the source file. The reason that the program has died here is that, in Limbo, all external modules must be explicitly loaded before they can be used; to try to call an uninitialised module is an error and causes an exception. .SH More sophisticated debugging .PP .CW Stack is fine for getting a quick summary of the state in which a program has died, but there are times when such a simple post-mortem analysis is inadequate. The .CW wm/deb (see .I wm-deb\fR(1))\fP command provides an interactive windowing debugger for such occasions. It runs outside Acme, in the default window system. A convenient way to start debugging an existing process is to raise .CW wm/task (``Task Manager'' on the main menu), select with the mouse the process to debug, and click ``Debug''. This will start .CW wm/deb on that process. Before it can start, the debugger will ask for the names of any source files that it has not been able to find (usually this includes the source for the shell, as the module being debugged is often started by the shell, and so the top-level function will be in the shell's module). .PP .CW Wm/deb can be used to debug multiple threads, to inspect the data structures in a thread, and to interactively step through the running of a thread (single stepping). See .I wm-deb (1) for details. \" further afield? \" other development tools? \" tools to come?