home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 582b.lha / OCT_v1.93.13B / ReadMe.1st.pp / ReadMe.1st
Text File  |  1991-12-08  |  12KB  |  290 lines
  1. (2-march-91 bjw)
  2. (14-nov-90 bjw)
  3. (23-oct-90 bjw)
  4. (20-sept-90 bjw)
  5. (9-sept-90 bjw)
  6. (19-apr-90 bjw)
  7. (22-dec-89 bjw)
  8. (29-aug-89 bjw)
  9.  
  10.  
  11.              OOOOOO       CCCCCCC      TTTTTTTTTTTT
  12.             O      O     C       C          TT
  13.             O      O     C                  TT
  14.             O      O     C                  TT
  15.             O      O     C                  TT
  16.             O      O     C       C          TT
  17.              OOOOOO       CCCCCCC           TT
  18.  
  19.  
  20. Greetings!
  21.  
  22.     This disk contains source code and examples for an object
  23.     oriented C preprocessor system.  Included are many classes
  24.     to get you going.  The system includes some support programs
  25.     to manipulate the data, too.  Much of the system is based on
  26.     Dr. Cox's 1986 book, "Object Oriented Programming: An
  27.     Evolutionary Approach", (Addison-Wesley).  Much of the source
  28.     code is from there.
  29.  
  30.     The files follow closely version 2 of Objective-C.  There are
  31.     a many version 4-ism added.  For instance, classes are declared
  32.     with "@implementation" instead of ":=" style.  The foundation
  33.     classe have been NeXT style aligned.  The OCT system was built
  34.     mostly by referencing Dr. Cox's book.
  35.  
  36.     The system was developed by Brian Witt during 1989, 1990 and 1991.
  37.     The software includes 'flex' from FSF (from Fred Fish #156) and
  38.     'cpp' from DECUS.  The 'cpp' includes additions done after
  39.     Fred Fish #28.  The 'flex' program is included in its entirity.
  40.     Both programs are stored in a zoo format to save space.
  41.  
  42.  
  43. LICENSE:
  44. --------
  45.         <<< THIS SECTION UNDER CONSTRUCTION >>>
  46.  
  47.     Please distribute all files intact and without modifications,
  48.     unless the author of those modifications indicates clearly the
  49.     files affected.  There are no warrenties, expressed or implied
  50.     as to the suitability or usability of the provided files.  The
  51.     authors don't accept liability for any consequental damages.
  52.     Complete copyright notices are in the root directory.
  53.  
  54.     The software not covered by DECUS and FSF licenses, or other
  55.     people/organizations constitutes the OCT software system.
  56.     The "collection of the programs stored on this disk" is not
  57.     copyright.  Parts covered by DECUS or FSF licenses must be 
  58.     distributed persuant to the programs' originator's restrictions.
  59.     The programs developed specifically to support the Object-
  60.     Oriented "C" system constitute the OCT software system.  These
  61.     specific programs can be used for fun and recreation.  Profit
  62.     motives must be cleared with the author, with written persmission,
  63.     beforehand.
  64.  
  65.     The OCT software system is copyright 1989, 1990, 1991 (c) by
  66.     Brian J. Witt, as intellectual property, ALL RIGHTS RESERVED.
  67.     The OCT software system is in the public view, and other parties
  68.     may not sell it for profit or personal gain. Costs for distribution
  69.     may, however, be recovered. If you wish to add warrenties or
  70.     services beyond those already provided, a fee may be changed for
  71.     services rendered (GNU style). The author(s) of the OCT software
  72.     system reserve the right to modify or amend the terms covering
  73.     their contributed works.  If you have questions about these terms,
  74.     or any others here, please contact the respective authors.
  75.     
  76.     For the OCT software system to be distributed, it must be
  77.     distributed in whole, and contain all licences of the included
  78.     software.  If you plan on using the OCT software system, please
  79.     flatter the author with mail.  You may freely sale a system based
  80.     on the runtime libraries, provided all copyright notices are
  81.     included with your distribution.  Please mention the OCT system,
  82.     and this author along with DECUS and FSF in the documentation.
  83.  
  84.     The object code of the runtime and class libaries, and the class
  85.     interface header files may be distributed freely and without
  86.         restriction.
  87.  
  88.     The FSF requires that software built using its code must be
  89.     available freely.  A way to obtain their code used in the system
  90.     must be stated.  The 'flex' program may be found on Fred Fish #156.
  91.     The 'cpp' program may be found on Fred Fish #28.  Copies of these
  92.     diskettes are available from local computer stores, this author,
  93.     and Fred Fish himself.
  94.         <<< THIS SECTION UNDER CONSTRUCTION >>>
  95.  
  96.  
  97.  
  98. DISK LAYOUT:
  99. ------------
  100.  
  101.     The directories are divided amoung these groups: base system
  102.     source code, run-time source, and sample application code.
  103.     All these directories are brought together in the  root directory.
  104.  
  105.     The translator system source is stored in "xlator".   Only hackers
  106.     should peek inside. There are a few sample code directories.
  107.         "samples" includes a test suite of torture programs, and "maker"
  108.         is from Dr. Cox's book: dependency graphs (ch. 6).  An incomplete
  109.         windowing system is included in "view".
  110.  
  111.     System programs compiled and ready to run are store in :bin.
  112.     See the Makefiles in the samples section for how to use them
  113.     in a 'Makefile'.  The programs include a short help description.
  114.     The class and substrate libraries are stored in "lib".
  115.  
  116.  
  117. DISPERSING:
  118. -----------
  119.  
  120.     The running system requires one logical assignment to locate
  121.     the root its private directories.  The following layout is
  122.     recommended.  About 2 meg is required if you unpack and de-zoo
  123.     all the files.  Each directory on the disk has a Zxxx.zoo file.
  124.     These should be unpacked if you're going to use the files therein.
  125.  
  126.       OCT: ---+----- xlator         (optional; translator source)
  127.               |       |
  128.               |       +----- cpp            (optional)
  129.               |
  130.               +----- bin            (required; Amiga executables)
  131.               |
  132.               +----- docs           (required!)
  133.               |
  134.               +----- methods        (required; methods)
  135.               |
  136.               +----- collect        (optional)
  137.               |
  138.               +----- include        (required; headers)
  139.               |
  140.               +----- tools          (optional)
  141.               |
  142.               +----- unix           (optional)
  143.  
  144.  
  145.         include --+----- objc       (required)
  146.                   |
  147.                   +----- apps       (required)
  148.                   |
  149.                   +----- collect    (optional)
  150.  
  151.  
  152.         sys  ------- lib            (required; Amiga class libraries)
  153.  
  154.         sys  ------- usr/include    (optional additional includes)
  155.  
  156.  
  157.  
  158.     The include directory contains various files.  Having this bunch
  159.     of files in one space should reduce setup time.  If you don't have
  160.     the files "stdlib.h" and "string.h" copy them from usr/include to
  161.     somewhere public.  Both are required to recompile the foundation
  162.     classes and substrate.  The file "tree.h" is also required to
  163.     recompile the translator.
  164.  
  165.     The "methods" directory contains the contents of the base library.
  166.     The Makefile takes a few minutes to run, but the system must be
  167.     rebuilt if you change any methods in this directory.  Just 'make'
  168.     will build a test app, 'make lib' builds the class library.
  169.  
  170.     The bin directory on the floppy contains compiled versions of the
  171.     programs, plus the zoo program.  These programs should be included
  172.     in your CLI path somewhere.
  173.  
  174.     The LIB directory must be copied to your system library directory.
  175.     If it isn't LIB: and you plan on modifying the foundation classes,
  176.     you must change the Makefile in :ooc/methods.
  177.  
  178.     The source to 'cpp' and 'flex' are provided to satisfy licensing,
  179.     and need not be unzoo'ed.  Copy and unpack the files in their
  180.     directories if you're interested in them.
  181.  
  182.  
  183. UNIX RUNNING:
  184. -------------
  185.     The file 'setup' presets some ksh environment variables.  Better
  186.     make sure you get these preset before trying to translate any source!
  187.     There aren't may others settings except in the Makefiles.
  188.  
  189. INCLUDE="$HOME/myoct/usr/include:$HOME/myoct/include" ; export INCLUDE
  190. OCTCPP="-DNO_PROTOTYPE -+" ; export OCTCPP
  191. echo "OCT INCLUDE shell var is now set."
  192.  
  193.     Inside the Makefile's are #A comments (maybe #U comments).  These
  194.     relate to the Amiga and UNIX systems.  Probably should create a
  195.     Makefile.cpp instead...  For the xlator Makefile, ensure the 
  196.     'install' method deposits the executables in the correct "bin"
  197.     directory.
  198.  
  199.  
  200. FIRST INSTALLATION:
  201. -------------------
  202.  
  203.     Build the cpp program first, then cd .. to xlator and build that.
  204.     Test the compiler by typing: (cd ../test ; make suite).  This
  205.     should produce lots of output.  Look for "successful translation"
  206.     just before that Makefile invokes 'cc'.  There is one or two
  207.     warnings that appear; those are OK.  Once you're happy, install
  208.     the translator and oct-cpp by typing 'make install'.
  209.  
  210.     You are now ready to build the class libraries.  Move into
  211.     myoct/methods and adapt the Makefile to your location just like
  212.     in myoct/xlator.  (You should also adapt the Makefile in
  213.     myoct/collect and myoct/maker; the headings are very similar.)
  214.     Type make to produce a substrate test routine called 'main16.'
  215.     Ensure that this program runs to compeletion.  Make sure that
  216.     #ByteArray lines have test after the s3 " output.  To install
  217.     the library, type 'make install' again.
  218.  
  219.     Now go back into myoct/test to type 'make app' to create a test
  220.     application.  This one exercises memory allocation and test
  221.     pointer alignment situations.  After running main16 sucessfully,
  222.     the system is ready for eral use.
  223.  
  224.     Move cd into myoct/collect and type 'make' there.  Then test that
  225.     main16 here runs OK.  Then type 'make install'
  226.  
  227.     The sample application is from Cox, 1986 (first edition).  It is
  228.     a simple dependency graph example.  I've extended the grammar
  229.     to handle comments (ala Makefile's).  Build that by moving into
  230.     myoct/maker and typing 'make' which will also build a hello world
  231.     type program called 'hw16'.  It prints a string, then prints the
  232.     reverse of that string.  Run the dependency example by typing
  233.     'main16 depends'.
  234.  
  235.  
  236. AMIGA RUNNING:
  237. --------------
  238.  
  239.     Unpack and the read the documentation.  I spent a lot of time writing
  240.     it, and I expect you to spend time studying those files! :-) :-)
  241.     There are 'man' pages for the individual files; you may want to
  242.     copy them to your central man-page repository. To use the system,
  243.     you'll need something like: ASSIGN OOC: <place>, and have the path
  244.     set to include the executables.
  245.  
  246.     Once the executables are installed, try making the dependency graph
  247.     example.  If you just type 'main', a built-in graph will be
  248.     constructed, or you can use the data file provided.  Manx's 'sdb'
  249.     may be used to step through the application. Start with:
  250.         sdb -s/methods!/maker main depends
  251.     Issue:
  252.                     G app_main
  253.     Then 't'race message expressions!  A breakpoint set inside of
  254.     _msg() where it calls the method code is good place to decide
  255.     whether to trace over or single step into the methods.
  256.  
  257.     The "view" system is not at all complete; it's combined from many
  258.     ideas, including those from ch. 9 of Cox's book.  It's a nice place
  259.     to start from, if you understand the code.
  260.  
  261.  
  262. PORTING:
  263. --------
  264.  
  265.     The system was built on the Amiga 1000.  The Manx Aztec 3.6A compiler
  266.     has 16-bit int's and signed char's.  Long idenitifer names (about 14
  267.     chars should do) were used both for internal and external function
  268.     names.  The substrate library (OCT run-time) is all standard "C".
  269.     The translator and classes have been tested with 32-bit int's on
  270.     a Xenix '386 system.
  271.  
  272.     At run-time, pointer location (char *)0 should contain (char)0.
  273.     The translator shouldn't need this, though (I hope).
  274.  
  275.     The .m files may be traced using a symbolic debugger since the
  276.     translator outputs #line directives.  Very handy stuff, you know!
  277.  
  278.  
  279.   *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *
  280.                    "Laws seldom stop politicans"
  281.  
  282.     Internet:  brian@babbage.ecs.csus.edu
  283.     USENET:    { unisoft | uunet.UU.NET } seer!rael!aleks
  284.  
  285.     USMAIL:    Brian Witt
  286.                3638 Perada Dr.
  287.                Walnut Creek, CA  94598-2712
  288.                USA
  289. (eof)
  290.