home *** CD-ROM | disk | FTP | other *** search
/ Complete Linux / Complete Linux.iso / docs / devel / smalltal / readme.stx < prev    next >
Encoding:
Text File  |  1994-03-29  |  7.5 KB  |  230 lines
  1. Welcome to the Smalltalk/X educational distribution !
  2. -----------------------------------------------------
  3.  
  4. Please read LICENSE for what you may/may not do with this
  5. package.
  6.  
  7. This release is not bug-free - some bugs are known, many 
  8. are still to be found. Please have a look at 'doc/bug_list'
  9. for what is already known.
  10.  
  11. You are welcome to send notes/bug-reports to:
  12.  
  13.         clam!st_bug @ ssw.de
  14. or:
  15.         office @ tomcat.de
  16.  
  17. (but please check if not already in the list, or if it 
  18.  wasn't just a misunderstanding 
  19.  - otherwise, I may probably not find time to do anything 
  20.    else than reading mails in the future :-)
  21.  
  22.  
  23. running Smalltalk/X
  24. -------------------
  25.  
  26.     setenv DISPLAY ...
  27.  
  28.     cd smalltalk
  29.     smalltalk
  30.  
  31. the directory-hierarchy found here is self contained, 
  32. meaning that other directories, files or installation are not 
  33. needed to run Smalltalk/X; just tar-it-in and execute smalltalk.
  34.  
  35.  
  36. installing Smalltalk/X
  37. ----------------------
  38.  
  39. If more than one person is going to use Smalltalk/X, it is
  40. useful to install the common files in some standard places,
  41. and have the private files per-user.
  42. For most file accesses within Smalltalk/X, it uses a searchpath,
  43. allowing users to override things usually found in the common
  44. place.
  45. (the path looks like:
  46.                      . 
  47.                      $HOME/.smalltalk 
  48.                      $SMALLTALK_LIBDIR
  49.                      /usr/local/lib/smalltalk
  50.                      /usr/lib/smalltalk
  51.  
  52.  in this order.
  53. )
  54.  
  55. For example, a personal startup-script 'smalltalk.rc' can be
  56. put into '$HOME/.smalltalk/smalltalk.rc'.
  57. (see more in doc/manuals/configuration).
  58.  
  59.  
  60. To install the system into some standard place 
  61. (usually '/usr/local/bin' and '/usr/local/lib'), 
  62. you should create the following directories:
  63.  
  64.         /usr/local/lib/smalltalk
  65.         /usr/local/lib/smalltalk/source
  66.         /usr/local/lib/smalltalk/resources
  67.         /usr/local/lib/smalltalk/bitmaps
  68.         /usr/local/lib/smalltalk/doc
  69.  
  70. and copy the files from corresponding subdirectories 
  71. found here to those new directories.
  72. Also, all files ending in '.rc' and '.stc' should be copied
  73. to the new directory.
  74.  
  75. If you do not have access to '/usr/local/lib', you can also
  76. put the stuff wherever you like AND set the shell-variable
  77. 'SMALLTALK_LIBDIR' to whatever the name of this directory is.
  78.  
  79. Thus, your global directory should look like:
  80.  
  81.         ./source
  82.         ./source/*.st
  83.         ./resources
  84.         ./resources/*.rs
  85.         ./bitmaps
  86.         ./bitmaps/*.xbm
  87.         ./fileIn/...
  88.         ./doc/coding
  89.         ./doc/misc
  90.         ./doc/...
  91.         ./smalltalk.rc
  92.         ./smalltalk_r.rc
  93.         ./display.rc
  94.         ./d_*.rc
  95.         ./host.rc
  96.         ./h_*.rc
  97.         ./abbrev.stc
  98.         ./patches
  99.  
  100.  
  101. Since compiled code does not include the source code itself, 
  102. but instead a reference (filename & position) to it, 
  103. an incorrect installation will lead to no sourcecode being shown
  104. in the browser 
  105. (the 'smalltalk.rc' script does a quick check and gives a warning).
  106.  
  107. Also, please do not manually edit the source files themselfes -
  108. you will make the position-information in compiled code invalid, 
  109. and also see funny source code (parts only) later.
  110.  
  111. This package does not include all sources - some stuff is only
  112. avaliable in the non-free release. Therefore some methods sourcecode
  113. will not be visible in the browsers - even with a correct installation. 
  114.  
  115.  
  116. startup actions
  117. ---------------
  118.  
  119. During startup, ST/X reads a file called 'smalltalk.rc' to
  120. setup some internal stuff. Since the search for this file is done
  121. using the above path, you can put your private 'smalltalk.rc' into
  122. either the current directory or '$HOME/.smalltalk'.
  123.  
  124. This script will first do some display-specific setup (using
  125. 'display.rc'), then some host-specific stuff ('host.rc')
  126. and finally launch some default applications (currently the
  127. Transcript and Launcher). You can of course add more to this
  128. (for example, if you like to arrange for a browser to come
  129.  up automatically).
  130.  
  131. 'display.rc' tries to find out the kind of display hardware
  132. you are working with, and then executes one of the 'd_xxx.rc'
  133. scripts. have a look at 'display.rc' and change it as required.
  134. You should leave the existing 'd_xxx.rc'-files unmodified - 
  135. better add your own new one, and call it 'd_<displayname>.rc'.
  136.  
  137. 'host.rc' tries to find out, what host you are running on
  138. (which is NOT always the same as the display in X). Host
  139. specific setup consists mainly of printer setup.
  140. Also, you should leave those existing files alone, and add 
  141. a new one, called 'd_<hostname>.rc'.
  142.  
  143.  
  144. The second script called 'smalltalk_r.rc' is consulted, when 
  145. a snapshot image is restarted; it also does display- and host
  146. setup but not launch any new applications.
  147.  
  148.  
  149. making fixes permanent
  150. ----------------------
  151.  
  152. Fixes can be made permanent by appending the fix to the 'patches' 
  153. file, which is also read at initial startup.
  154.  
  155. Thus, any changes you dont want to re-apply manually after a 
  156. new fresh start, should be put into the patches file.
  157.  
  158. The ChangesBrowser has a special entry to do this ('make change
  159. permanent').
  160.  
  161.  
  162. surviving a crash
  163. -----------------
  164.  
  165. In contrast to other smalltalks, the snapshot image does not play a
  166. central role in ST/X. You can easily live without one.
  167. In case of a crash, you can (even without image) start ST/X anew,
  168. and apply the changes made using the ChangesBrowser.
  169. If your changes have already been made their way into the 'patches'
  170. file, no manual actions are required.
  171. (notice: to do so, you need a private 'patches' file, which must be 
  172.  in the current directory)
  173.  
  174. Do not depend exclusively on the image - its a good idea to "fileOut" 
  175. your classes in regular intervals - it happened in the past, that images 
  176. where not readable, and a clean start had to be done.
  177.  
  178. I suggest, you add your new applications classes to the autoload-
  179. list (see 'patches'-file for how this is done).
  180.  
  181. Also, since "fileOut" saves its stuff in the current directory, its a
  182. good idea to use different directories for different projects.
  183.  
  184.  
  185. Some warnings / notes before you get frustrated
  186. -----------------------------------------------
  187.  
  188. The editTextView used in the FileBrowser has a bug in not handling TABs 
  189. correctly (in this release) - it will convert all tabs to spaces 
  190. on output. Thus, you should not edit Makefiles with the FileBrowser.
  191.  
  192. Submenus sometimes do not appear - instead a warning "GrabNotViewable"
  193. is output - this is a known bug in the popup-views grab handling.
  194.  
  195.  
  196. how to start
  197. ------------
  198.  
  199. There is some lack of documentation in this release, therefore you
  200. will have to find your way yourself (this will change ...).
  201.  
  202. However, I suggest you use the fileBrowser, and have a look at
  203. the coding examples in 'doc/coding', the small demo programs in
  204. 'doc/Demos' and finally the more complex demo applications (DrawTool,
  205. LogicTool etc.). Also the document 'doc/misc/beginner' (which is 
  206. a misnomer) gives a list of useful selectors.
  207.  
  208. If you want to do some programming with views, take a look at
  209. 'doc/misc/quick_view_intro', which gives a step-by-step introduction,
  210. and will teach you in 5 minutes, how to create views, buttons etc.
  211.  
  212. These documents can also be accessed through the launchers menu.
  213.  
  214. For the language itself and the basic classes, please refer to standard 
  215. literature, I recommend the wonderful book:
  216.  
  217.         "Smalltalk-80, The language and Implementation"
  218.  
  219. to everybody. It can be used also as a reference guide, since
  220. most information found there is also valid for ST/X.
  221.  
  222.  
  223. fin
  224. ---
  225.  
  226. Have fun with smalltalk. I hope this distribution helps to
  227. get more people hooked to this great programming language !
  228.  
  229. - Claus (cg@ssw.de)
  230.