home *** CD-ROM | disk | FTP | other *** search
/ develop, the CD; issue 1 / Apple_Develop_1989.bin / dynamo / buildapp.manual.text < prev    next >
Text File  |  1989-12-10  |  34KB  |  816 lines
  1. Getting started:    Setting up the DYNAMO cross-development system:
  2.  
  3.  
  4. Step 1:    Copy the DYNAMO folder onto your Macintosh.  Then rename 
  5. the folder to indicate the project.
  6.  
  7. Step 2:    Create a ProDOS disk.  It should be initialized at a 4:1 
  8. interleave.  ProDOS should be copied onto it (get the ProDOS file from a 
  9. bootable ProDOS 8 disk, or get the P8 file from the System folder of a 
  10. GS/OS disk and rename it to ProDOS on the floppy).  The 
  11. BUILDAPP.SYSTEM and BUILDAPP.TEXT files (found in the folder 
  12. prodos.stuff) should be copied to the ProDOS disk via Apple File 
  13. Exchange or copied over a server.  When copied to the ProDOS disk, the 
  14. filetype/auxtype of BUILDAPP.SYSTEM should be $FF/$0000, and the 
  15. filetype/auxtype of BUILDAPP.TEXT should be $04/$0000.
  16.  
  17. Step 3:    Start MPW by clicking on any of the source files in the project 
  18. directory.  Do a full-build of SAMPLE.  When prompted, insert the ProDOS 
  19. disk.
  20.  
  21. Step 4:    Insert the ProDOS disk into the Apple II (or IIGS).  Boot it.  
  22. (Or double click on BUILDAPP.SYSTEM from the finder.)
  23.  
  24.  
  25. You should now be running the DYNAMO sample application.  This sample 
  26. is simply an exerciser of the DYNAMO runtime routines.  It tests the routines, 
  27. and also the source code demonstrates using the runtime and macro 
  28. libraries.
  29.  
  30.  
  31.  
  32. Now, for more detail:
  33.  
  34.  
  35.  
  36. The BUILDAPP.SYSTEM program allows the developer to build a 
  37. multiple-segment application into one program file, and to launch it simply 
  38. on the //e.  Segments are automatically relocated to appropriate banks of 
  39. memory, and then the application is launched starting at any address in any 
  40. bank chosen.
  41.  
  42. BUILDAPP.SYSTEM uses a text file as a script for building the application.  
  43. The default name for this text file is BUILDAPP.TEXT.  This can be 
  44. changed by modifying the pathname in the program BUILDAPP.SYSTEM.  
  45. The pathname starts at the sixth byte of the file, memory location $2006 if 
  46. BLOADed.  The pathname is a pascal string.  (This is the standard ProDOS 
  47. way of giving the launched application a pathname.)
  48.  
  49. To use the BUILDAPP.SYSTEM program, you will need a disk with 
  50. ProDOS, the BUILDAPP.SYSTEM program, a build script file called 
  51. BUILDAPP.TEXT, and all the segments of your application on one disk.  
  52. This disk is now bootable.  When the disk is booted, BUILDAPP.SYSTEM 
  53. will construct a single executable block of code starting at address $2000.  
  54. Then it will prompt you as to whether or not you want to save this image.  
  55. During development, you will often choose not to save it, since it takes just 
  56. that much longer to get the application executing.  Then you can test your 
  57. latest addition or change to your application.  To make a bootable disk 
  58. without BUILDAPP.SYSTEM, you just save the application image to disk 
  59. when prompted, and then copy the application to a disk with just ProDOS 
  60. on it.  If the application name ends with .SYSTEM, and it has a filetype of 
  61. $FF, you have a bootable application.
  62.  
  63.  
  64. You may wish to develop on one machine, which writes the segments to the 
  65. ProDOS disk, and then just boot the disk on another machine.  This saves a 
  66. lot of time booting into your development environment.  There is also the 
  67. advantage of always being able to look at the most current source while 
  68. executing the program.  You don't need two machines to develop, but it will 
  69. definitely speed up the add/change/test development cycle every 
  70. programmer goes through.
  71.  
  72.  
  73.  
  74. How the application is build depends on the BUILDAPP.TEXT script file.  
  75. Here is the explanation of this file:
  76.  
  77. The first line of the build script is the pathname that will be placed at $2006 
  78. of the application.  You may have no need for this, but if you are 
  79. developing a system application, launchers may place a pathname there, and 
  80. you may want a default.
  81.  
  82. Lines 2-N are for the segments to be loaded.  The first field is the mode 
  83. byte.  Bits 0-2 of the mode byte indicate what bank of memory the segment 
  84. should be transferred to at execution time.
  85.  
  86. Bit 0 indicates ROM or language card.  Off for ROM, on for language card.
  87.  
  88. Bit 1 indicates which language card (if bit 0 is on).  Off for primary 
  89. language card, on for auxiliary language card.
  90.  
  91. Bit 2 indicates 1st or 2nd $D000 bank of language card.  Which language 
  92. card is still indicated by bit 0 and 1.  Off selects the secondary $D000 bank 
  93. ($C083), and on selects the primary $D000 bank ($C08B).
  94.  
  95. Bit 3 indicates primary or auxiliary 48k.  Off for primary, on for auxiliary.
  96.  
  97. Bit 4 indicates that the auxiliary stack pointer should NOT be initialized.  If 
  98. you load a block of code or data into the auxiliary language card, the 
  99. auxiliary stack pointer is initialized to $FF unless you indicate otherwise by 
  100. setting this bit on.
  101.  
  102. Bit 7 of the mode byte being on indicates the end of the segment list.  Bits 
  103. 0-3 still indicate a bank of memory, and the following field indicates the 
  104. launch address within that bank.
  105.  
  106. The second field is the load address.  This is the address the segment will be 
  107. moved to at execution time.
  108.  
  109. The third field is the name of the segment itself.  This can be a full or partial 
  110. pathname.
  111.  
  112. The next two lines indicate whether you want hex or decimal information 
  113. indicating starting address and total application size.
  114.  
  115. The final line indicates the application filetype, auxtype, and filename.  The 
  116. application builder will ask if you want the application saved.  After the file 
  117. is saved (or not), the application is launched for testing.
  118.  
  119. All numeric fields can be decimal or hex.
  120.  
  121. The below is a sample build script that was used to make the application 
  122. builder itself.  
  123.  
  124. There is only one segment for this application.  The runtime was linked into 
  125. the main code module, generating only one binary code segment.
  126.  
  127. BUILDAPP.TEXT            ;The default script filename.
  128. 0,$800,BUILD.BIN        ;The buildapp application.
  129. $80,$800                ;Starting address.
  130. $                        ;Display starting address in hex.
  131. $                        ;Display application size in hex.
  132. $FF,0,BUILDAPP.SYSTEM    ;Filetype, auxtype, and filename.
  133.  
  134. The BUILDAPP.TEXT file can be up to 2045 bytes long.
  135.  
  136. Bank switching will still have to occur within the application, as necessary.  
  137. There is no getting around that on a //e.  BUILDAPP.SYSTEM is to 
  138. simplify the loading and starting of an application, by making it a single, 
  139. launchable file.
  140.  
  141.  
  142.  
  143. Below are the macros included in the runtime, and their basic usage:
  144.  
  145. ____________________________________________________________
  146. _
  147.  
  148. OPERAND USAGE:
  149.  
  150. If the operand represents an integer variable or string, then you do not put a 
  151. # in front of it.  Variables and strings are always either a ldx literal, or a ldy 
  152. literal, so the # is assumed.  When the macro is expanded, the # is put there 
  153. automatically.
  154.  
  155. If the operand represents a value, then you will need to put a # or an * in 
  156. front of the operand.  If you put a # in front of the operand, then it is a 
  157. literal.  If you put an * in front, then it uses the value at that address.  This 
  158. is similar to the C unary operator *.
  159.  
  160. These macros are interfaces for the runtime routines associated with them.  
  161. The runtime routines handle up to 128 integer variables, and up to 256 
  162. strings.  The runtime also has multi-dimension array support.  The integer 
  163. functions are simple add,sub,mul,div, and others.  These others include 
  164. mass-initialization, min, max,  print decimal, etc.  The string functions are 
  165. most of what is available in AppleSoft, in various forms.  The array 
  166. functions are used to define a base pointer to a row of dta within the array, 
  167. and then to index into and out of that row.
  168.  
  169. The principle of the runtime routines is that the xreg holds a destination 
  170. variable number (for ints: 0-254, for strings: 0-255).  All runtimes preserve 
  171. the xreg, therefore, you can do multiple operations to a single variable 
  172. without having to reload the xreg.  The values that are used on the xreg 
  173. variable (the source data), is one of 3 forms for integers:
  174.     1. 1-byte value
  175.     2. 2-byte value
  176.     3. 2-byte integer variable.
  177. 1-byte values are placed in the acc.  2-byte values are placed in the acc,y 
  178. (acc=lo, y=hi).  2-byte integer variables have the variable number placed in 
  179. the yreg.  (The yreg is not preserved by the runtime routines.)  Once the 
  180. source