======================= bkasm README Bret Victor, 7/8/03 ======================= Welcome to bkasm! WHAT IS? -------- bkasm is a powerful, extensible, Perl-based cross-assembler designed for small embedded processors, particularly digital signal processors. It currently supports the AL3101 "1K" DSP from Alesis Semiconductor, and additional targets may be accommodated easily. STATUS ------ bkasm is beta software. This means that all features and functionality slated for the v1.00 release have been implemented, but have not necessarily been thoroughly tested. The bkasm User's Guide is a work in progress. It is currently about 60% written, and about 0% edited. Apologies. For the material still uncovered, you should hopefully be able to glean or guess the basics from the Automatic, the Appendices, and the example source files. The major hole is the linker, which is currently almost completely undocumented. I hope to have some linker examples soon. The User's Guide is formatted for double-sided printing. Binding and placement next to comparable works of fine literature are recommended as well. But if you'd rather read it as a PDF, note that all page numbers and section references are hyperlinked for quicker jumping to. The internal documentation in the source code is hit-or-miss. Some sections are commented spectacularly; in other sections, the Perl-to-English ratio is far too high. This situation will hopefully get cleaned up by v1.00. UPDATES AND FEEDBACK -------------------- News and updates are available at: http://bkasm.souceforge.net If you find bugs or errors in the manual (including typos in either software or text), PLEASE go to: http://sourceforge.net/projects/bkasm/ click on "Bugs", and submit an entry to the bugtracker. If you have questions or comments, please post in the forums (also accessible from the above website) or send me an email. INSTALLATION FOR WINDOWS USERS ------------------------------ This archive contains a file "bkasm.exe", which functions as a standalone executable. No need for any fancy installer -- just copy this program to wherever you want it and run it from the command line. That's probably all you'll need to do. However, if you want to modify or extend bkasm, you will have to install Perl. If you don't have it already, you can get Perl from here: http://www.activestate.com/Products/ActivePerl/ Once Perl is installed, you should invoke bkasm by typing "perl bkasm.pl" (Windows 98) or "bkasm.pl" (Windows 2000/XP). If you are doing this, of course, you probably already know what you are doing. INSTALLATION FOR NON-WINDOWS USERS ---------------------------------- bkasm is a Perl program, which means that it will run anywhere that Perl runs, which is pretty much anywhere. If you are working on a Unix-like system (including Linux or MacOS X), chances are you already have Perl installed. To check, go to a command prompt and type "perl -v". If Perl tells you that it is v5.6.0 or later, you're good to go. If your Perl is too old or too non-existent, go to: http://www.perl.com Once you know you have Perl, type "which perl" to find out where it is on your system. Then: 1. Open up bkasm.pl in a text editor, and change the first line of the file so it indicates where Perl is on your system. 2. At the command line, type "chmod +x bkasm.pl" to make the file executable. 3. Type "ln -s bkasm.pl bkasm" to create a symlink named "bkasm". You should then be able to run bkasm by typing "bkasm". GETTING STARTED --------------- Read the first couple chapters of the User's Guide, and look at the files in the examples/ directory. LICENSE INFORMATION ------------------- This program is free software; you may redistribute it and/or modify it under the terms of the Artistic License. For more information, see LICENSE.txt or "http://www.opensource.org/licenses/artistic-license.php". AUTHOR ------ Bret Victor (bret@ugcs.caltech.edu) http://www.ugcs.caltech.edu/~bret ............................................................................ copyright (c) 2003 Bret Victor, and the space between us two.