Amiga ISO Collection

home *** CD-ROM | disk | FTP | other *** search

/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / 3_1DOCS.DMS / in.adf / Instructions < prev next >

Wrap

Text File | 1993-12-08 | 17.0 KB | 421 lines

3.1 Amiga Developer Update Disks (c) Copyright 1985-93 Commodore Amiga, Inc. All Rights Reserved Some additional copyrights may be noted in individual files and docs. These materials are not freely redistributable. However some individual archives on these disks may contain their own licensing or redistribution information. In addition, a license for the 3.1 Includes and linker libs is available from Commodore (see Licensing Info section below). Instructions ============ Welcome to the 3.1 Amiga Developer Update disk set. These disks contain includes files, libs, autodocs, examples, tutorials, and debugging tools for developing Amiga software for versions V38 (2.1), V39 (3.0) and V40 (3.1) of the Amiga OS. These materials can also be used to develop code for earlier version of the Amiga OS, since the materials include all earlier OS structures and functions. There is a lot of material here. The "Contents" file on this disk contains a full list of everything included on this disk set. Please note that very few of the files and directories on these disks have icons. To see all of the files on the disks, use the Show All feature of 2.0 and higher Workbench, or use the Amiga shell. This document will give you an overview of what's provided on the disks, and some help with decompressing the archives and using the materials. What's Here =========== Docs disk highlights -------------------- 1. Autodocs The Amiga autodocs are the function summaries for the V40 Amiga OS. In general, all functions, libraries, and devices from previous Amiga OS's are also covered. Please note that narrator.device and the translator.library are not currently part of the Amiga OS, and are not licensable, so please don't write software which requires these. Also, all functions newer than 1.2 are generally marked with the first version number in which they appeared. 2. Tutorials These are tutorial documents about new features of V38 and V39. AA graphics, locale, bullet, datatypes, and other features are discussed. But you won't find AA register descriptions. Use the OS. New V40 (3.1) libraries and devices are not covered, but there are autodocs for these (lowlevel.library, nonvolatile.library, cd.device). Licensed AmigaCD developers receive additional docs and examples for these new V40 subsystems. See additional notes about 3.1 at the end of this document. 3. Contents listing A full listing of the contents of the 3.1 Amiga Developer Update disks. Use this to find what you are looking for. 4. LHEX If you don't have LhA by Stefan Boberg, the LHEX tool provided on the Examples2 disk can also be used for decompressing the archives on this disk. The flags for LHEX are slightly different from the flags for LhA, and LHEX has fewer options and only supports decompression. For information on decompressing the archives on these disks, see "Decompressing the Archives" later in these Instructions. Includes&Libs disk highlights ----------------------------- 1. Amiga include files The include_h.lha archive contains the C include files. The include_i.lha archive contains the assembler include files. I believe it is no longer possible to fit all of the include files on a normal density diskette, even if formatted with fast filesystem. If you have a hard disk, decompress both archives to the same directory. If you have a floppy based system, you'll probably want to decompress them each to a separate disk. 2. Linker_libs and FD's Here are amiga.lib, debug.lib, etc. and the FD (function definition) files for V40. The LVO tool (SWToolkit3 disk) can be used with the FD files to list LVO offsets and other information. 3. Using_Includes A readme about updating your development environment, and about compiling new and old code with the new 3.1 Includes. Includes hints for beginners on what include files to include. 4. StructOffsets.lha Contains the Structure.Offsets file for 3.1 which lists the sizes, member sizes, and member offsets of 3.1 Amiga structures. 5. DevTools archive Contains tools for development like bumprev and autodoc, plus old code tools like ALink and Atom. 6. Debug_Examples archive Contains example code using kprintf, and C include files with simple debugging macros you can turn on and off (much neater than having a lot of #ifdefs in your source code). 7. startups37 archive The 2.0 Amiga startup code source and objects - useful for assembler code, and for Amiga-specific non-base-releative C code that doesn't require your compiler's startup code but needs command line argument parsing and/or handling of Workbench startup. 8. SetPatch37.lha and SetPatch40.lha These archives contain updates to SetPatch to fix OS bugs and in some cases enhance compatibility. SetPatch37.lha contains SetPatch 37.39 for Amigas running V37 (2.04) Kickstart. SetPatch40.lha contains SetPatch 40.14 for Amigas running V38 (2.1) through V40 (3.1). Each archive includes a click-on installation script and readme. 9. runtime_libs.lha This archive contains iffparse.library 37.1 and realtime.library 34.5 for use on Amiga systems that don't already have these libraries. Free electronic licenses are included for distribution of these versions. V37 and higher systems already have iffparse.library, but versions 38 and upwards of this library require at least V37 OS. V40 Workbench includes a realtime.library that requires at least V37 OS. The earlier versions supplied here work under 1.3, and should even work under 1.2 (not tested). IFFParse.library is required by the NewIFF39 code modules and examples. Realtime.library is a new library that provides a way for tasks to share high resolution timing and also to synchronize with each other. See the autodoc realtime.doc in the V40 autodocs for more information. Examples1 Disk highlights ------------------------- Code examples for many new V38 and V39 features including locale, intuition, asl, colorwheel, graphics, gadtools, and asynchio packets example. The locale examples include special code you can link with to load your own locale catalogs under V37, and a tool to help you automate some of the work in localizing old code. Note - the CatComp tool for creating catalogs and its doc are on the SWToolKit3 disk. The Locale tutorials are on the Docs disk in the tutorials archive. Of special note - PCMCIA.lha contains several tutorial articles about PCMCIA and some useful tools and examples, plus information on ordering the PCMCIA specs. Examples2 Disk highlights ------------------------- Big code archives for NewIFF39 (1.3-compatible yet AA-capable IFF code modules and examples), DataTypes examples, new picture datatypes, and also the AmigaGuide archive featuring free electronic license for AmigaGuide. Notes - the Datatypes tutorial is on the Docs disk in the tutorials archive. The NewIFF archive includes a ScreenSave program and the ILBM slide show program Display. SWToolkit3 highlights --------------------- This disk contains all of the Amiga debugging tools, other handy tools, and the Amiga "report" program for generating bug reports and enhancement requests in the correct format. Here you'll find Mungwall, Enforcer, Wedge, new Wack (archived), IO_Torture, Sushi (captures debug output on one machine), LVO, and other important debugging tools. A new setcamg tool is here also - useful for zapping the display mode of ILBMs. Here you will also find the CatComp tool for making locale catalogs. The docs for all of the Toolkit tools are archived on this disk. Tools with large doc files will have their own .doc files, and the rest are documented in OtherTools.doc. Some tools are documented in the .doc files of the main tool with which they are distributed. See the beginning of OtherTools.doc for a listing tells you where to find the docs for such tools. Note - some older tools such as ShowLocks and SysPM have been left in the toolkit even though they have not been updated. Of special note - - New Enforcer for V37 and up (old Enforcer now called Enforcer1.3) - SegTracker. Start this up right after SetPatch! It allows many other tools to report Hunk and Offset information for code hits and crashes. See Enforcer.doc - FindHit. If you have compiled or assembled your code with LINE debugging, FindHit can tell you a source code line from hunk and offset information. See Enforcer.doc - Sushi. Allows use of all serial debugging tools and kprintf on a single system, without writing to your actual serial hardware, modems, etc. (note - you must use the Enforcer RAWIO option for Sushi to pick up Enforcer output) - Updated Mungwall and Munglist - Wedge updated to use much less stack Using The Amiga Developer Update Materials ========================================== These materials are intended to be used in conjunction with the Amiga Rom Kernel programming manuals and examples for Release 2.0. The 2.0 Rom Kernel manuals published by Addison-Wesley, plus The AmigaDOS Manual published by Bantam are the official programming manuals for the Amiga. If you program for 2.0, it is easy to add V39/AA support by conditionally using the V39 32-bit-per-gun color loading functions to support the palette of 16,000,000 AA colors. Fish Disks 741 and 742 include the 2.0 RKM Companion archives which contain the examples from the Amiga ROM Kernel Reference Manuals, 3rd edition. Fish Disk 344 contains the 1.3 RKM Companion archives which contain the examples from the Amiga ROM Kernel Reference Manuals, 2nd edition. The materials on these disks may be used to program for earlier versions of the Amiga OS. For earlier OS's, don't use features, flags, structures, or functions which were added later. Then add code to conditionally use any new functions which replace older methods of allocation or setting of flags. Read the compatibility documents in this disk set and in the Release 2 ROM Kernel Manuals. Published by Bantam Books (800-223-6834, NY & Canada 212-765-6500): The AmigaDOS Manual 3rd Edition ISBN 0-553-35403-5 Published by Addison-Wesley (800-447-2226, 617-944-3700): Amiga User Interface Style Guide ISBN 0-201-57757-7 Amiga Hardware Manual ISBN 0-201-56776-8 Amiga ROM Kernel Manual: Includes and Autodocs ISBN 0-201-56773-3 Amiga ROM Kernel Manual: Devices (includes the IFF manual) ISBN 0-201-56775-X Amiga ROM Kernel Manual: Libraries ISBN 0-201-56774-1 About 3.1 and CD32 (V40) ======================== At the time of this writing, the 3.1 operating system has only been released in the Amiga CD32. It is also available to registered developers in our closed electronic conferences for testing on other Amiga models. If you wish to develop CD-ROM software for CD32, you must sign an AmigaCD license for your product. Licensed AmigaCD developers have access to additional materials and tools for programming the CD32. If you are developing an CD32 CD-ROM product, contact CATS - Licenses, 1200 Wilson Drive, West Chester, PA. 19380 (or FAX 215-429-0643) and request AmigaCD license forms. Include your name and full surface mail address. Becoming a Registered Developer =============================== Developers in our registered Amiga developer programs receive special mailings, discounts, and access to beta OS and other materials in our closed electronic conferences on BIX, CIX (UK), and ADSP (Europe). In the US, two programs are currently available. The Certified program costs approximately $100/year. To join the Certified program, you must be developing a saleable product for the Amiga. The Commercial program costs approximately $500/year, and includes personal phone support. The Commercial program is only open to developers with existing commercial computer products. If you are developing a saleable product for the Amiga and would like a developer program application, this can be requested in the US from CATS-Applications at 1200 Wilson Drive, West Chester, PA. 19380 (or FAX 215-429-0643). Licensing Info ============== These materials are not freely redistributable. However some individual archives on these disks may contain their own licensing or redistribution information (including AmigaGuide.lha, SetPatch archives, and runtime_libs.lha). An inexpensive distribution license for the 3.1 Includes and linker libs is available from Commodore. Also available are licenses for earlier versions of the Includes. In addition, Workbench licenses are available for Workbench 1.3, Workbench2.0, Workbench 2.1, and Workbench 3.0 (a Workbench 3.1 license should be available soon). Workbench licenses allow distribution of most of the files on a specific version of the Workbench disks, but do not include Arexx, CrossDOS, or outline fonts. Includes and Workbench licenses do not allow any type of freely copyable distribution, and do require specific copyrights on your disk labels, and specific copyrights and disclaimers in your documentation. The cost for an Includes license is currently $25 US/year. The cost for a Workbench license is currently $100 US/year. Renewals require documentation of compliance ith the license. Licenses forms may be requested by name in the US by contacting CATS-Licenses at 1200 Wilson Drive, West Chester, PA. 19380 (or FAX 215-429-0643). Be sure to include your name, phone number, surface mail address, and the name(s) of the license(s) you require (i.e. Includes 3.1, Workbench 3.0, etc.). Decompressing the Archives ========================== NOTE - in all of the examples below, the archive names are shown without paths. Unless the archive is in your current directory, you must supply a full path to where the archive file is. Example: LHEX x df0:DevTools/DevTools.lha If you have enough RAM, dearchiving may go faster if you copy the archive to RAM: first, then dearchive it. All of the usage examples also assume that your dearchiving tool is in one of your command paths. Copy the dearchiving tool somewhere convenient where the system can find it (like to SYS:Tools, or to RAM: and then do PATH RAM: ADD) 1. Tools If you have LhA by Stefan Boberg, you'll probably want to use that to decompress the archives. LhA is fast and flexible. If you don't have Lha, a tool called LHEX is provided on the Examples2 disk. LHEX is a tool from CATS for decompressing archives. Its command line switches are fewer and different from LhA's. 2. General - Listing the archive LhA Usage: lha v archivename LHEX Usage: lhex l archivename (or just LHEX archivename) Before decompressing any archive, you should list the archive to see if it will be placing everything in a directory or not. This will determine where the destination for decompression should be. For example, when we list the contents of include_h.lha, we see that the files are stored as include/<directory>/<file>.h, as below: [generic] 4542 35.8% Oct 15 10:24 include/clib/alib_protos.h [generic] 1136 19.1% Oct 15 10:25 include/clib/all_protos.h (etc.) This shows that when we decompress this archive, it will create if necessary and dearchive into a directory called "include". This means we should decompress the archive to parent directory of our current "include" directory. The easy way to direct the destination for decompression is to CD to the directory where you wish the archive contents to go. In the above case, this means we WOULD NOT CD into our existing "include" directory, but rather to its parent directory. For example, if our include directory is Work:SC/include, we would CD to Work:SC, since the listing of the include archive shows it will want to find (or create) a directory called "include". Alternately, if you have enough RAM, the safest way to decompress archives is to make a temporary directory in RAM: (called "tmp" or whatever). CD into the temporary directory, and decompress the archive there. Then COPY ALL the files to the place where you want them. If you are short on RAM, You could do the same by CD'ing to a temporary directory on your hard drive. 3. Decompressing an entire archive LhA Usage: LhA -rexa x archivename LHEX Usage: LHEX x archivename The -rexa options for LhA tell it to preserve attribute bits, and create directories even if empty. That's the same way LHEX decompresses. The above usage will decompress the archive to your current directory. To decompress an entire archive to somewhere other than your current directory: LhA Usage: LhA -rexa x archivename destdir (must end with / or :) LHEX Usage: LHEX -w=destdir x archivename 4. Extracting individual files or directories from an archive LhA Usage: LhA -rexa x archivename filepattern LHEX Usage: LHEX x archivename filepattern Note - I believe the filepattern may be case-sensitive. First, list the archive to find the full path and name of the file or directory you wish to extract. Then extract it. Examples: LhA: LhA -rexa x autodocs.lha doc/amigaguide.doc LhA -rexa x NewIFF39.lha newiff39/modules/* LHEX: LHEX x autodocs.lha doc/amigaguide.doc LHEX x NewIFF39.lha newiff39/modules/*