lynnjenn@vef.north.net Enchanted Blade Associates R.R. 4 Langton, Ontario N0E 1G0 Canada --------------------------------------------------- bc 1.00 - a command line compiler for Blitz Basic 2 --------------------------------------------------- ·Abstract· For a long time now, users of Blitz Basic 2 (BB2) have wished they could use an editor other than TED, the editor that comes with the BB2 package. This package, best described as a `hack' (you've been warned), will let you do it. The bc package consists of a short script that invokes TED and the bbc program, the program bbc itself which does all the work, and a default bc.config file for configuration settings for bbc. Invoking bc with appropriate file options will cause a source file to be either run (like a "Compile/Run") or turned into an executable (like a "Create File"). This should be considered a beta release. It is hoped by the author that the useful life of this program is short, that is, that a true command line compiler will be put out by Acid soon. ·Installation· The package consists of the files indicated. The directory next to the file name is the place where you should copy it (no install script is included; installation is pretty simple). File Copy To Purpose --------- ------------ --------------------------------------------------- bc S:bc Compiles files by invoking bbc (called by user) bbc C:bbc Takes over TED to perform actual compilation bc.config S:bc.config Allows user-control of various bbc settings bbc.src#? Source code for the bbc program¹ test.src A test program (source code) for the bc package bc.doc Documentation for the bc package --------------- ¹ Note that according to the licence for this program, a copy of any changes you make to the source code that you wish to distribute must be sent to Enchanted Blade Associates (this is only so that we can distribute a version that incorporates all of the best changes in one single package). We encourage you to improve the program. ·Configuration· If your TED editing screen is not 640 x 200 (i.e. if you are using an interlaced or PAL screen), you will have to modify certain lines in the default bc.config file. The bc.config file contains information on how to do this. ·Using the Compiler· The bc package consists of two programs. The only one you will ever use is "bc". In fact, bc is not a program but a shell script (a script is used to make it easy to change certain aspects of the system, such as where the bbc program is located; there is a better way, but I didn't have time to throw it in last night, see the source code for more details). It runs your BB2 editor, telling it to load your source file, and then starts bbc, passing it your command arguments. The bbc program then does the actual work. There are two ways to run the compiler: in "run" mode and in "create" mode. In "run" mode, your program will be compiled and then run so you can see the results. In "create" mode, your program will be turned into an executable file. The command line syntax of bc is as follows: bc source [executable|run] A source file must be indicated. If the second argument is "run", then the program will be compiled in "run" mode. Otherwise, the second argument is the file name for the executable in "create" mode. If no second argument is given, the program is run in "create" mode using a file name created by removing the extension from the source file name (e.g. "code.bb2" becomes "code"). NOTE: If your "bc" program doesn't run, you may have accidentally unset its file attributes. Try "protect s:bc +se". ** ** ** WARNING! Do not use the "CloseEd" command with programs you intend ** ** to compile using bc. Never, never, ever! ** ** ** Here's what should happen when you compile a program: 1 A brief welcome message should be displayed by the compiler. 2 The BB2 TED editor screen should appear. 3 The TED welcome window should appear. 4 The window's gadget should flash, then the window should close. 5 The source code should be loaded and appear in the edit window. 6 The menus should appear, and the "COMPILE" menu should be picked. 7 The "COMPILE/RUN" or "CREATE FILE" item should be picked. If in "run" mode: 8 The program should compile and run. (Continue when program ends.) If in "create" mode: 8 The "Create File" requester should appear; your file name should be typed into, and it should be compiled and saved. 9 If there was a compile error (e.g. syntax error), close the error message window before proceeding. 10 A window from "bc" should appear on the TED screen with instructions. When you close the window or press the left and right² mouse buttons: 11 The "PROJECT" menu, then "QUIT" should be selected. 12 TED, and bc, should exit. -------------- ² Press and hold the left button, then click the right. You may need to do this once or twice if bc isn't listening at the exact fraction of a second that you press them. ·Problems· Problems with the compile process can usually (i.e. in every case I have seen) be handled by changing your configuration file. The most common problem (once you get the screen settings taken care of) is program size. The size of the "Load Delay Ticks" setting must be large enough for TED to have enough time to load your program. The default setting of 100 is high enough for most small to medium sized programs if you are running off a good hard drive. If you make your program bigger and suddenly have problems compiling, or if you notice a problem starting at around step 4-5 (from above), this is the most likely cause. Why? bbc sends simulated menu selection messages to TED; if the program has not yet loaded then these messages will be ignored so no compiling will take place. Increase the number to increase the time alloted to load the source code. If your source is on floppy, increase the value _a lot_. You may find a local configuration file valuable. Read the included default "bc.config" file for more suggestions. If you solve some problem heretofore undescribed in this documentation, please write to us with your problem and the solution you used so we can help others avoid your problems. ·The Configuration File· The included bc.config example file is a good place to start configuring your system. You may have already made changes to it for your TED screen size. There are three ways that bbc can get its configuration information. When you run bc, it will tell you which method it is using in square brackets. If there is a "bc.config" file in the current directrory, it will be used. This is noted by bc with "[Using local configuration]". If there is no local bc.config, bbc will look for one in your S: directory. If it finds one, this is noted with "[Using global configuration]". If it can't find one there either, it will use built-in defaults, which it notes with "[Using default configuration]". You should avoid using the default configuration. It won't work properly unless you are using a 640 x 200 editor screen. Once you have set up the included bc.config for your system, you should copy it to your S: directory. It will then become the global default so that any new project will use it. When you need special settings for one certain project, such as when a file grows too big for your default Load Delay Ticks, copy the configuration from S:bc.config to your project directory and make changes to your local copy. See the default configuration file for an explanation of the various settings and what they effect. The included file is an exact match of bbc's default (internal) configuration. You should keep it in a safe place. ·In Closing· We hope that this makes your life a little easier until a real command line compiler coes out. We invite and encourage you to make changes and improvements, but remember to send us a copy (uuencoded email or mailed disk) so that we can combine everyone's improvements into a single, improved bc (you will get credit for your work). Also feel free to send bug reports or other comments. You can find lots of help and suggestions for making changes and improvements in the actual source code. ·Sleep Deprivation Disclaimer· If anything is mistyped or poorly written, or the source code unusually stupid or hard to follow, please understand that I have whipped this up in a late night non-stop programming/documentation session. I was tired when I started, and right now I am in rather desperate need of either a coffee or a bed. ·Copyright, etc.· The bc software and related files and documentation ("package") are copyright © 1995 by Enchanted Blade Associates. All rights reserved. You are hereby given permission to distribute this package freely for non-commercial use. You may charge a reasonable duplication/media fee for the distribution of this package (not more than $7/disk or $50/cd Canadian, including all shipping, handling, and other fees but excluding taxes). You may not charge for electronic distribution of the package (such as over the Internet or other networks, or through a bbs, or via modems), although you may charge for membership or use of that network or other entity as long as no additional charge is made for the distribution of the software. By using this software you agree to be bound by the following licence: 1 As this package is provided free of charge for general use, you agree that you use this package and rely on its results entirely at your own risk. You also agree to assume full responsibility for any damages incurred by the use, misuse, or abuse of this package, except where prohibited by law. This package is provided without warranty. 2 You agree that you may not use this package in conjunction with an illegal or "pirated" copy of Blitz Basic 2. 3 You agree that any changes you make to source code which you intend to distribute or which are significant in nature will be sent along with a short description to Enchanted Blade Associates. This may be done in the form of uuencoded email or a mailed diskette (address at top of document). In return, Enchanted Blade Associates agrees that, from time to time, they will release a new version of the program that incorporates all useful additions and changes into a single new version. You will receive credit for changes made from your source code (no other reimbursment is offered). END OF TEXT