home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / pocketbk / utilsr / s3c111 / MANUAL.TXT < prev    next >
Text File  |  1994-12-12  |  7KB  |  237 lines
  1.                       S3C
  2.  
  3.              C Compiler and Linker 
  4.           
  5.           For Psion S3 and S3a handhelds
  6.           
  7.               Giles Goddard 1994
  8.  
  9. V1.11B
  10.  
  11.  
  12. Before we get started heres an explanation about the compiler itself.
  13.  
  14. The compiler is based on the public domain 'SmallC' compiler written 
  15. originally by Ron Cain then modified heavily by Chris Lewis.
  16. It was obtained from CIX by jtd@cix and given to me. Many thanks John!
  17.  
  18. SmallC is a subset of C, that is, its real C with a few things
  19. left out or kept in from 'old' C. The only major difference is 
  20. that this version will not compile unions, enums and a few other things
  21. including types other than CHAR and INT, also all pointers are
  22. 16bits wide. Which works out quite nicely for EPOC machines.
  23. Segment registers are never touched.
  24.  
  25.  
  26. The idea behind the original compiler was to be able to produce output 
  27. for various types of architectures with the minimum amount of changes
  28. to the actual compiler source. The compiler ordinarily outputs machine
  29. code source which is then passed onto an assembler for that particlular 
  30. machine. However, the version that I have made outputs 'pseudo'
  31. raw object code which is passed straight on to a linker, which then
  32. has only to sort out label references and data orginisation.
  33.  
  34. Please read the file 'new.doc' for details of the what I've changed
  35. with the compiler and linker.
  36.  
  37. I plan to add unions and doubles/floats/longs support in the 
  38. future.
  39.  
  40. S3Link is a seperate stand alone linker written by me for use with
  41. S3C and S3Asm. The latest version of S3Asm can output compatible 
  42. object files ready for linking with S3C object files.
  43. S3Link outputs Psion's Image file format, which is the equivilent
  44. of DOS' .EXE files and can be easily made into an APP type file ready
  45. for installing on the system screen.
  46.  
  47.  
  48. Using S3C:
  49. ---------
  50. Using S3C is as easy to use as Psion's OPL Program application. 
  51. You edit your program, press Psion-T, and if everything has compiled
  52. and linked ok you should have a finished Image file. You can even
  53. get S3C to run that Image file from within the Program application 
  54. itself. Or you can just run it from under the RunImg icon.
  55.  
  56. S3Link appends startup code to your program that automatically opens 
  57. a console which it assigns to stdin, stdout and stderr, You can of course 
  58. turn this feature off and create your own display using the library of 
  59. EPOC functions. Or you can use the function 'openshell' included in 
  60. stdio to create a custon console. Its prototype is:
  61.  
  62. void openshell(int FONT, int COMPAT, int CURSOR, int WIDTH, int HEIGHT)
  63. where:
  64.  FONT is the font number to use.
  65.  COMPAT is FALSE/TRUE to turn S3 compatability mode OFF/ON 
  66.  CURSOR is FALSE/TRUE to turn OFF/ON the cursor.
  67.  WIDTH,HEIGHT is the size of the console window in characters.
  68.  
  69. (see the example file 'shell.c' for an example)
  70.  
  71.  
  72. The best place to get started writing your C programs is to look
  73. at the examples, 'win.c', 'shell.c' and 'hello.c' 
  74.  
  75.  
  76. Libraries
  77. ---------
  78. This version of S3Link doesn't actually know the difference between 
  79. object files and libraries. They're all linked together as one to produce
  80. the final output, so theres no dynamic library linking. ie. If you use
  81. one function in an object file, then you get given all of them in the
  82. final output file.
  83. But for now we'll assume that files like 'stdio.o' and 'e_*.o' are  
  84. library files.
  85.  
  86. There are some libraries providing all of the basic EPOC functions as 
  87. well as the Window Server functions included with this version. 
  88. They are called:
  89.  
  90.  e_*.o  - Where * is the name of the service they provide.
  91.  
  92.  
  93. Please refer to the EPOC O/S system services chapter or the
  94. Window server reference chapter in the SDK for more details.
  95. (This version does not include all V2 functions)
  96.  
  97.  
  98. These libraries are split up in this way in order to help with the
  99. limited amount of memory and speed of the S3/3a
  100.  
  101.  
  102. stdio:
  103. -----
  104.  
  105. This version of 'stdio.o' includes only a few very basic C functions,
  106. they are:
  107.  
  108. putchar()
  109. strlen()
  110. strcpy()
  111. strcat()
  112. ferror()
  113. perror()
  114. feof()
  115. fgetc()
  116. fgets()
  117. fputc()
  118. fputs()
  119. fopen()
  120. fclose()
  121. system()
  122. calloc()
  123. printf()
  124. sprintf()
  125. openshell()
  126.  
  127. Apart from openshell(), they are all the same as the standard C
  128. stdio library functions.
  129.  
  130.  
  131.  
  132.  
  133. Installing:
  134. -----------
  135.  
  136.  Unzip this zip file into an empty directory.
  137.  
  138.  Make sure you're connected to your Psion and that MCLINK can 
  139.  establish a link. 
  140.  
  141.  Go back into DOS and type 'install' RETURN
  142.  Then follow the prompts.
  143.  
  144.  This should run MCLINK in script mode and copy all the appropriate
  145.  files onto your Psion into M:
  146.  
  147.  If you would like to install onto a different drive then please 
  148.  change 'install.txt' and 'instepoc.txt'
  149.  
  150.  Now that everything is copied, install C.ALS on the
  151.  system screen, by pressing Psion-I
  152.  
  153.  And try it out!
  154.  
  155.  
  156. Files:
  157. ------
  158. This explains about the files in this version:
  159.  
  160. 'SYS$PRGC.IMG' is the Compiler and Linker program. DON'T try and run
  161. this from RunImg, it will most likely go horribly wrong. Its designed
  162. to be started from the Word application when it requests translation.
  163.  
  164. 'e_*.o' files are the EPOC and Window server library functions.
  165.  
  166. 'stdio.o' is basic IO and C functions, such as fopen, fgetc, strcat
  167. (see the STDIO part of this doc)
  168.  
  169. 'c.als' is an alias file which runs Word in program mode, and tells
  170. it to use 'SYS$PRGC.IMG' as the translator.
  171.  
  172. All C source(.C) and object(.O) files should be placed in one directory,
  173. preferably \C 
  174.  
  175.  
  176.  
  177. Contact:
  178. --------
  179.  
  180. If you have any suggestions, comments or bug reports then please
  181. send email to: Giles Goddard 
  182.  
  183.    gsg@cix.compulink.co.uk 
  184. or 
  185.    71125,532 - COMPUSERVE
  186. or
  187.    giles@twics.co.jp
  188.    
  189. or Snailmail:
  190.  
  191.     Giles Goddard
  192.     6, Court Royal Mews,
  193.     Northlands Road,
  194.     Southampton,
  195.     England.
  196.  
  197. (please note, that I actually live in Japan so snailmail may take longer)
  198.  
  199.  
  200. Thanks.
  201.  
  202.  
  203. Credits:
  204. --------
  205.  
  206. The compiler was originally written by Ron Cain and then heavily
  207. modified by Chris Lewis, then heavily modified by me (Giles).
  208.  
  209. S3Link and S3Asm was written by Giles Goddard.
  210.  
  211. Thanks to DavidW@psion (dw2@cix) for his help.
  212.  
  213.  
  214. Disclaimer:
  215. -----------
  216.  
  217. S3Link is copyright (c) Giles Goddard 1994
  218.  
  219. Neither the authors of this software or Psion Ltd. can be held
  220. responsible for any loss of data, hardware or lives as a result
  221. of using this software.
  222.  
  223.  
  224. S3C is Public Domain and may not be sold in any form.
  225.  
  226. S3Link is Shareware-ish. If you would like to link bigger files than
  227. Slink currently allows, then please make a small donation 
  228. (a tenner will do 8-) then email me. I will give you a code
  229. that goes on the link command line which removes the size limit.
  230.  
  231. You should be able to register S3C and S3Link on compuserve soon.
  232. Please email me for details.
  233.  
  234. S3Asm is Shareware.
  235.  
  236.  
  237.