
This  DOC file commences a very extensive coverage (350K+) on  the
excellent  package  Devpac V2.  The manual is  divided  into  many 
parts,  all of which may be found on this Sewer Doc Disk Number 8. 
Special thanks once again to the Animal House who typed the entire 
manual single-handedly.  Quite a good effort and one which will be 
beneficial to many ST programmers out there.  This file (and every 
one of these files) was edited by Sewer Rat.  


                            CHAPTER  1
                           INTRODUCTION


ALWAYS MAKE A BACK-UP

     Before  using DevpacST you should make a back-up copy of  the 
original disk and put the original away in a safe place. It is not 
copy-protected  to allow easy back-up and to avoid  inconvenience. 
This  disk  may  be backed up using the  Desktop  or  any  back-up 
utility.

     Before hiding away your master disk make a note of the serial 
number (if you have an original???   Then you would not be reading 
this.!!)

REGISTRATION CARD

     Enclosed  with the manual is a registration card  (sorry  not 
for  you,  and you get a free 68000 Pocket Guide [ œ2.95 from  any 
good bookshop. ] )

THE README FILE
     
     As  with  all Hisoft products DevpacST is  continually  being 
improved and the latest details cannot be included in this  manual 
may be found in the README.S file on the disk. This file should be 
read  at  this  point,  by double clicking on its  icon  from  the 
Desktop and the clicking on the Show button.  You can direct it to 
the printer by clicking on the Print button.

THE DEVELOPMENT CYCLE

The purpose of DevpacST is to allow you to enter assembly language 
programs,  assemble  them to machine-code and debug them if  (  or 
should  that be 'when' {oh! sarcasm!} ) they don't work. Depending 
on  your  application,  you  may also be using a  linker  to  join 
together  seperate modules,  possibly with the output from a  high 
level  language  compiler.  Of course the faster  the  development 
cycle,  the  faster you can get your programs up and  running  and 
DevpacST was designed to be as fast and powerful as possible.
     The link stage is optional, as is the Compile stage.



                       DEVPAC DISK CONTENTS


PROGRAMS

GENST2.PRG     GEM screen editor and assembler
MONST2.PRG     the GEM program debugger
MONST2.TOS     the TOS program debugger
GENST2.TTP     stand-alone version of assembler
AMONST2.PRG    auto-resident debugger 
CHECKST.PRG    diagnostic program
LINKST.TTP     GST-format linker
NOTRACE.PRG    trace exception dis-abler
MENU2ASM.TTP   menu compiler


TEXT FILES

README.S       latest details about DevpacST
DEMO.S         very simple TOS program used in tutorial
GEMTEST.S      simple GEM demo program
DESKACC.S      example desk accessory
GEMMACRO.S     macros for AES/VDI interface
AESLIB.S       AES library source
VDILIB.S       VDI library source
NOTRACE.S      source to NOTRACE.PRG
MENUTEST.S     example GEM program using menu
MENUTEST.MDF   sample menu definition file
MAKEGEM.S      creates GEMLIB
GEMLIB.LNK     control for GEMLIB


BINARY FILES

GEMLIB.BIN     AES & VDI library


FOLDERS

OLDGEM         update GEM examples from GenST 1



                      HOW TO USE THE MANUAL

     This manual makes no attempt to teach 68000 assembly language 
programming or to detail the instruction set.  For the former, the 
bibliography  lists  suitable  books,  while for  the  latter  the 
supplied  Pocket  Guide is very useful.  The  Appendices  give  an 
overview of the technical aspects of the Atari ST but they are not 
intended as a complete technical description of the machine.
     This manual is set out in five chapters, this introduction, a 
chapter on the screen editor,  a chapter on the macro assembler, a 
chapter on the debugger, then a chapter on the linker. In addition 
there  are  eight  Appendices  which  detail  various   additional 
information.  We suggest you use the manual in a way that  depends 
on what type of user you are;


DEVPACST VERSION 1 USERS

Turn  to  Appendix  H  and read the  section  describing  the  new 
features,  then  read  the Reference section of Chapter 4  if  you 
intend  using MonST,  as it has changed  considerably.  The  other 
section  you may read is that on File Formats in Chapter 3 if  you 
are interested in generating linkable code.


BEGINNERS

     If you are a newcomer to assembly language then we  recommend 
that you read one of the books in the Bibliography alongside  this 
manual.
     At  the end of this chapter there is a simple tutorial  which 
you should follow to familiarise yourself with the use of the main 
parts of the program suite.
     Chapter  2  details  the editor and is  well  worth  reading, 
though much of Chapter 3,  detailing the assembler,  is liable  to 
mean  nothing  until you become  more  experienced.  The  Overview 
section  of  Chapter 4,  the debugger,  is  strongly  recommended, 
though  Chapter  5  and the Appendices can be left  for  a  while. 
Looking  at the supplied source code may be helpful,  but the  GEM 
programs  may  be  hard going as they were not  written  with  the 
beginner in mind.


EXPERIENCED USER

     If you are experienced in the use of 68000 assembly  language 
but have not used DevpacST before then here is a very quick way of 
assembling a source file:

     Load GENST2.PRG,  Press Alt-L and select your file which will 
load into the editor. Press Alt-A and select the options which you 
require  - if generating executable code then click on the  Memory 
button  for  additional  speed.  Pressing RETURN  will  start  the 
assembler, which may be paused by pressing Ctrl-S, Ctrl-Q resumes. 
Any assembly errors will be remembered and on return to the editor 
you  will  be placed on the first one.  Subsequent errors  may  be 
found by pressing Alt-J.
     
     To  run your successfully-assembled program (if assembled  to 
memory ) press Alt-X. If assembled to disk press Alt-O then select 
the program.

     As  a  quick  introduction  to  the  debugger  the  following 
tutorial is recommended.  If you have any problems please read the 
relevant section of the manual before contacting us for  technical 
support.


A VERY QUICK TUTORIAL

     This  is a quick tutorial intended to let you see  how  quick 
and easy it is to edit, assemble and debug programs with DevpacST.
     In  this tutorial we are going to assemble and run  a  simple 
program,  which  contains two errors,  and debug it.  The  program 
itself  is  intended to print a message and wait for a key  to  be 
pressed before quitting.
     To  start  with load GENST2.PRG from your back-up  copy  (you 
have  made  a backup,  haven't you?) which must also  contain  the 
files MONST2.PRG and DEMO.S, at minimum, by double clicking on its 
icon. After a short delay the screen will show an empty window; to 
load  the  file you should move the mouse over the FILE  menu  and 
click on LOAD. The standard GEM file selector will then appear and 
the file we want is called DEMO.S.  You may either double-click on 
the name or type it in and press RETURN to load the file.
     When  the file has loaded the window will show the top  lines 
of the file.  If you want to have a quick look at the program  you 
may click on the scroll bar or use the cursor keys.
     With  most  shorter  programs  it is best  to  have  a  trial 
assembly  that doesn't produce a listing or binary file  to  check 
the syntax of the source and show up any typing errors and so  on. 
Move the mouse to the  Program menu and click on Assemble.
     A dialogue box will appear, which should be left alone except 
the button near the bottom,  labelled NONE,  should be clicked on. 
Click on the Assemble button or press RETURN and the assembly will 
begin.
     The   assembler  will  report  an  error,   instruction   not 
recognised, and pressing any key will return you to the editor. he 
cursor will be placed on the incorrect line and the error  message 
displayed in the status line.
     The program line should be changed from MOV.W to MOVE.W so do 
this,  then  click on Assemble form the Program menu  again.  This 
time  click on the Memory button,  this means the program will  be 
assembled  into memory,  instead of onto disk.  This is very  much 
faster  and  allows you to try things out  immediately,  which  is 
exactly what we want.  Clicking on the Assemble button will  again 
assemble  it,  and after you press a key to return to  the  editor 
it's ready to run.
     The  assembly  worked this time,  so click on  RUN  from  the 
Program menu,  and what happens?  Not a lot it would seem,  except 
that a couple of bombs appear briefly on the screen - oh,  there's 
a bug.
     The  tool for finding bugs is a debugger,  so click on  Debug 
from the Program menu.  The debugger is described more fully later 
on,  but for now we just want to run the program from the debugger 
to 'catch' the bombs and find out what causes them, so press Ctrl-
R.
     After a brief delay the message Bus Error will appear in  the 
bottom  window,  with the disassembly window showing  the  current 
instruction
                    MOVE.W    1,-(A7)
     This  will  cause  a  bus error  because  location  1  is  in 
protected  memory  which cannot be accessed in user mode  -  there 
should be a hash sign before the 1 to put the immediate value 1 on 
the  stack.  To return to the editor press Ctrl-C,  so we can  fix 
this bug in the source code.
     Press Alt-T, to go to the top of the file, then click on Find 
from the Search menu.  We are going to find the errant instruction 
so enter
                    MOVE.W
     then press Return to start the search.  The first  occurrence 
has  a hash sign,  so press Alt-N to find the next,  which is  the 
line
                    MOVE.W    C_CONIN,-(A7)
     Ahah! - this is the one, so add a hash to change it to 
                    MOVE.W    #C_CONIN,-(A7)
     then assemble it again.  If you click on RUN from the Program 
menu you should see the message,  and pressing any key will return 
you to the editor.
     However,  did  you  notice  how messy the screen  was  -  the 
desktop  pattern  looked very untidy and you  possibly  got  mouse 
'droppings'  left on the screen.  This was because DEMO is  a  TOS 
program running with a GEM screen - to change this,  click on  RUN 
WITH GEM from the Program menu - the check mark next to it  should 
disappear.  If  you select RUN again you see the display is a  lot 
neater,  isn't  it?  If you run a GEM program you must ensure  the 
check mark is there beforehand, otherwise nasty things can happen.
     Although  the  program  now works we  shall  use  MonST,  the 
debugger,  to trace through the program,  step by step. To do this 
click on Debug from the Program menu, and the debugger will appear 
with the message Breakpoint, showing your program.
     There are various windows, the top one displaying the machine 
registers, the second a disassembly of the program, the third some 
other memory, and the bottom window displaying various messages.
     If you look at window 2, the disassembly window, you will see 
the current instruction, which in our case is
                    MOVE.L    #STRING,-(A7)
     As  the  debug was specified in the source code  any  symbols 
will appear in the debugger.
     Let's check the area around string Press Alt-3 and you should 
see the window 3's title inverted. Next press Alt-A and a dialogue 
box will appear, asking WINDOW START ADDRESS? - to this enter
                    string
     (it  must  be  in lower-case) and  press  RETURN.  This  will 
re-display  window 3 at the address,  showing the message in  both 
hex and ASCII.
     To  execute  this MOVE instruction press  Ctrl-Z.  This  will 
execute the instruction then the screen will be updated to reflect 
the  new  values of the program counter and register  A7.  If  you 
press Ctrl-Z again the MOVE.W instruction will be executed. If you 
look  at  the hex display next to A7 you should see a word  of  9, 
which is what you would expect after that instruction.
    The  next  instruction is TRAP #1 to call GEMDOS  to  print  a 
string,  but  hang  on - would we notice a string printed  in  the 
middle of the MonST display?  Never fear. MonST has its own screen 
to avoid interference with your program's,  to see this press  the 
V  key,  which will show a blank screen,  ready for your  program. 
Pressing any other key will return you to MonST.
     To  execute this call press Ctrl-z,  which will have  printed 
the string.  To prove it press V again,  then any key to return to 
MonST.
     Press Ctrl-Z twice more until you reach the next  Trap.  This 
one  waits for a key press so hit Ctrl-z and the program  displays 
will automatically appear,  waiting for a key.  When you're ready, 
press the q key.  You will return to MonST and if you look at  the 
register  window the low 8bits of register D0 should be  $71,  the 
ASCII code for q,  and next to that it will be shown as q  (unless 
in low-res.)
     The final Trap quits the program. So to let it run its course 
press  Ctrl-R,  you will then return to the editor as the  program 
has finished.
     Note the way  we have used the  Ctrl-X to mean hold the  Ctrl 
key  and  press the key X,  whilst Return or  RETURN  means  press 
return.
      

                         END OF CHAPTER 1
                         ÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿ

  
