home *** CD-ROM | disk | FTP | other *** search
/ Mega Top 1 / os2_top1.zip / os2_top1 / APPS / PROG / C_PLUS / EMX09A / INSTALL.DOC < prev    next >
Encoding:
Text File  |  1995-01-28  |  15.6 KB  |  512 lines
  1. ===============================================================================
  2. install.doc       emx 0.9a     INSTALLATION GUIDE                   05-Dec-1994
  3. ===============================================================================
  4.                                      Copyright (c) 1990-1994 by Eberhard Mattes
  5.  
  6. Introduction
  7. ------------
  8.  
  9. Welcome to emx 0.9a, an environment for creating 32-bit programs for
  10. OS/2 2.x (and DOS) with the GNU C compiler.
  11.  
  12. To use the GNU C compiler with emx, you need at least
  13.  
  14.   emxrt.zip     emx runtime package
  15.  
  16.   emxdev.zip    files required for developing programs with emx
  17.  
  18.   gnudev.zip    the GNU C compiler, the GNU debugger, and other tools
  19.                 (it should also be possible to use a different C compiler)
  20.  
  21.   gppdev.zip    additional files for GCC required for compiling C++
  22.                 programs
  23.  
  24.   gobjcdev.zip  additional files for GCC required for compiling
  25.                 programs written in the Objective C language
  26.  
  27. and
  28.  
  29.   unzip.exe     a free program for unpacking ZIP files
  30.  
  31. The following packages are optional:
  32.  
  33.   emxview.zip   emx documentation in OS/2 .inf format
  34.   emxsrcd.zip   source for emx devlopment tools
  35.   emxsrcr.zip   source for the emx runtime package
  36.   emxample.zip  sample programs
  37.   emxtest.zip   test programs (used for testing emx and the libraries)
  38.   gnuview.zip   gnudev.inf (gnudev.doc in OS/2 .inf format)
  39.   gnudoc.zip    documentation for GNU programs (texinfo sources)
  40.   gnuinfo.zip   GNU texinfo (includes info file browser)
  41.   gnupat.zip    patches for GNU sources
  42.   gnusrc.zip    patched GNU sources (ld, ar, nm, size, strip, objdump,
  43.                 info, termcap, GPPDEMID)
  44.   gccsrc1.zip   patched GNU sources (gcc 2.6.3, part 1)
  45.   gccsrc2.zip   patched GNU sources (gcc 2.6.3, part 2)
  46.   gccsrc3.zip   patched GNU sources (gcc 2.6.3, part 3)
  47.   gassrc.zip    patched GNU sources (gas 2.3)
  48.   gdbsrc1.zip   patched GNU sources (gdb 4.13, part 1)
  49.   gdbsrc2.zip   patched GNU sources (gdb 4.13, part 2)
  50.   gppsrc.zip    patched sources of libg++ 2.6.1
  51.   bsddev.zip    BSD libraries (curses etc.)
  52.   bsddoc.zip    documentation for BSD libraries
  53.   bsdsrc.zip    source for BSD libraries
  54.  
  55.  
  56. Preliminary tasks
  57. -----------------
  58.  
  59. IMPORTANT!  If there is an older version of emx already installed, you
  60. should delete the old version or rename the old directory.  Installing
  61. a new version over an old version is NOT RECOMMENDED.
  62.  
  63. Some of the emx batch files (such as texi2dvi.cmd) require REXX to be
  64. installed.  If you haven't installed REXX, use Selective Install to
  65. install it.  (Note to DOS users: REXX is OS/2's batch file language.)
  66.  
  67.  
  68. Installing the packages
  69. -----------------------
  70.  
  71. You should install all the packages on the same drive.  For instance,
  72. use
  73.  
  74.   c:
  75.   cd \
  76.   unzip emxrt
  77.  
  78. to install the emxrt.zip package on drive C:.  PKUNZIP cannot be
  79. used.  All the files will be installed in the \emx subdirectory or in
  80. subdirectories thereof.  The other packages are installed the same
  81. way.
  82.  
  83. After unpacking the emx runtime and development system packages,
  84. you'll find further information in the following files:
  85.  
  86.   \emx\doc\COPYING.EMX          emx & library license, license overview
  87.   \emx\doc\COPYING              GNU General Public License
  88.   \emx\doc\install.doc          Installation guide
  89.   \emx\doc\emxrt.doc            User's guide to the emx runtime package
  90.   \emx\doc\emxdev.doc           Application developer's guide
  91.   \emx\doc\libref.doc           C library reference
  92.   \emx\doc\build.doc            Compiling the sources
  93.   \emx\doc\history.doc          Change log
  94.   \emx\doc\future.doc           Things to do
  95.   \emx\book\emxrt.inf           .inf version of emxrt.doc
  96.   \emx\book\emxdev.inf          .inf version of emxdev.doc (optional)
  97.   \emx\book\libref.inf          .inf version of libref.doc (optional)
  98.  
  99. After unpacking the GNU and BSD packages, you'll find further
  100. information in the following files:
  101.  
  102.   \emx\doc\COPYING              GNU General Public License
  103.   \emx\doc\COPYING.LIB          GNU Library General Public License
  104.   \emx\doc\COPYING.BSD          BSD license (for libraries bsd and curses)
  105.   \emx\doc\COPYING.IOS          Additional information for iostream library
  106.   \emx\doc\gnudev.doc           GNU development tools information
  107.   \emx\doc\bsddev.doc           BSD library information
  108.   \emx\book\gnudev.inf          .inf version of gnudev.doc (optional)
  109.   \emx\book\bsddev.inf          .inf version of bsddev.doc
  110.  
  111.  
  112. Read history.doc first.
  113.  
  114.  
  115. Setting environment variables
  116. -----------------------------
  117.  
  118. OS/2 users should set the environment variables in config.sys, DOS
  119. users should set the environment variables in autoexec.bat.  Beware of
  120. blanks at the end of the lines!
  121.  
  122.  
  123. Developing programs on drive different from the installation drive
  124. ------------------------------------------------------------------
  125.  
  126. If you want to develop programs on a drive different from the drive
  127. where emx is installed, you have to set the C_INCLUDE_PATH and
  128. LIBRARY_PATH environment variables, for instance,
  129.  
  130.     set C_INCLUDE_PATH=c:/emx/include
  131.     set LIBRARY_PATH=c:/emx/lib
  132.  
  133. If you want to compile C++ programs, set CPLUS_INCLUDE_PATH as well:
  134.  
  135.     set CPLUS_INCLUDE_PATH=c:/emx/include/cpp;c:/emx/include
  136.  
  137. The genclass utility needs the following environment variable:
  138.  
  139.     set PROTODIR=c:/emx/include/cpp/gen
  140.  
  141. If you want to compile programs written in the Objective C language,
  142. set OBJC_INCLUDE_PATH as well:
  143.  
  144.     set OBJC_INCLUDE_PATH=c:/emx/include
  145.  
  146.  
  147. Speeding up compilation
  148. -----------------------
  149.  
  150. When compiling projects consisting of many modules (such as libraries)
  151. under OS/2, you can speed up compilation if you have enough memory by
  152. keeping GCC in memory.  For example, to keep GCC in memory for 5
  153. minutes, use
  154.  
  155.     set GCCLOAD=5
  156.  
  157. To make GCC use pipes instead of temporary files under OS/2, use
  158.  
  159.     set GCCOPT=-pipe
  160.  
  161.  
  162. Setting up termcap
  163. ------------------
  164.  
  165. To use GDB (the GNU debugger) and info (the GNU info browser) and other
  166. programs that use termcap, set the TERM and TERMCAP environment
  167. variables:
  168.  
  169.     set TERM=mono
  170.     set TERMCAP=c:/emx/etc/termcap.dat
  171.  
  172.  
  173. Setting up the info browser
  174. ---------------------------
  175.  
  176. Set the INFOPATH environment variable for info:
  177.  
  178.     set INFOPATH=c:/emx/info
  179.  
  180.  
  181. Setting up on-line documentation in OS/2 .inf format
  182. ----------------------------------------------------
  183.  
  184. To use the emx documentation in OS/2 .inf format, append c:\emx\book
  185. to the BOOKSHELF environment variable and define an environment
  186. variable which tells VIEW how to concatenate the .inf files.  Example:
  187.  
  188.     set BOOKSHELF=C:\OS2\BOOK;C:\EMX\BOOK
  189.     set EMXBOOK=emxdev.inf+libref.inf+gnudev.inf+bsddev.inf
  190.  
  191. To use the .inf files with EPM (the OS/2 Enhanced Editor), add the
  192. following line to your config.sys file:
  193.  
  194.     set HELPNDX=emxbook.ndx
  195.  
  196. If HELPNDX is already set in your config.sys file, add emxbook.ndx to
  197. the end of the HELPNDX variable, separated by a + character.
  198. Moreover, you should add c:\emx\book to the DPATH environment
  199. variable:
  200.  
  201.     set DPATH=...;c:\emx\book
  202.  
  203. where ... is the previous value of DPATH.
  204.  
  205.  
  206. Finishing the installation
  207. --------------------------
  208.  
  209. To finish the installation, add c:\emx\bin (insert the correct drive
  210. letter) to your PATH.  Add c:\emx\dll (insert the correct drive
  211. letter) to the LIBPATH statement in your config.sys file.  Reboot your
  212. computer to enable the new LIBPATH statement and the new environment
  213. variables.
  214.  
  215.  
  216. Creating desktop objects
  217. ------------------------
  218.  
  219. After rebooting, you can create a folder containing icons for the
  220. on-line books by typing
  221.  
  222.     emxinst
  223.  
  224.  
  225. Creating the OMF libraries
  226. --------------------------
  227.  
  228. To create the OMF libraries (for linking with LINK386), type the
  229. following commands after installing emx:
  230.  
  231.     cd \emx\lib
  232.     omflibs
  233.  
  234. The omflibs batch file builds .lib files from .a files.  If you
  235. install (after running omflibs) a package containing additional .a
  236. files , you should run omflibs again to build the .lib files for the
  237. new package.
  238.  
  239.  
  240. Using long file names on HPFS
  241. -----------------------------
  242.  
  243. To rename and patch the C++ header files for HPFS, type
  244.  
  245.     cd \emx\include\cpp
  246.     hpfs
  247.  
  248. To rename and patch the Objective C header files for HPFS, type
  249.  
  250.     cd \emx\include\objc
  251.     hpfs
  252.  
  253. You can revert to the FAT names by running `fat' instead of `hpfs'.
  254.  
  255.  
  256. Trouble shooting
  257. ----------------
  258.  
  259. If OS/2 says
  260.  
  261.     SYS1804: The system cannot find the file EMX.
  262.  
  263. when running a program compiled for emx, you haven't set LIBPATH
  264. correctly.
  265.  
  266.  
  267. Compiling a sample program
  268. --------------------------
  269.  
  270. Install the emxample.zip package:
  271.  
  272.   c:
  273.   cd \
  274.   unzip emxample
  275.  
  276. Compile the sieve program (optimizer enabled):
  277.  
  278.   cd \emx\samples
  279.   gcc -O2 sieve.c
  280.  
  281. Run the sieve program:
  282.  
  283.   sieve
  284.   sieve 100000
  285.   sieve -p 100
  286.  
  287.  
  288. Sample debugging session
  289. ------------------------
  290.  
  291. Compile the sieve program for debugging:
  292.  
  293.   cd \emx\samples
  294.   gcc -g sieve.c
  295.  
  296. Start the debugger and step through some lines:
  297.  
  298.   [D:\EMX\TEST]gdb sieve.exe
  299.   GDB is free software and you are welcome to distribute copies of it
  300.    under certain conditions; type "show copying" to see the conditions.
  301.   There is absolutely no warranty for GDB; type "show warranty" for details.
  302.   GDB 4.13 (emx), Copyright 1994 Free Software Foundation, Inc...
  303.   (gdb) set arg 10                                      <- set command line
  304.   (gdb) b isqrt                                         <- set breakpoint
  305.   Breakpoint 1 at 0x1004e: file sieve.c, line 45.
  306.   (gdb) run                                             <- start program
  307.   Starting program: d:/emx/samples/sieve.exe 10
  308.  
  309.   Breakpoint 1, isqrt (x=10) at sieve.c:45
  310.   45        l = 1; r = x;
  311.   (gdb) s                                               <- stop over one line
  312.   46        while (l < r)
  313.   (gdb) l                                               <- list source
  314.   41      static ULONG isqrt (ULONG x)
  315.   42      {
  316.   43        ULONG l, r, m;
  317.   44      
  318.   45        l = 1; r = x;
  319.   46        while (l < r)
  320.   47          {
  321.   48            m = (l+r) / 2;
  322.   49            if (m > 46340) m = 46340;
  323.   50            if (m*m < x)
  324.   (gdb) disp l                                          <- watch variable
  325.   1: l = 1
  326.   (gdb) disp r                                          <- watch variable
  327.   2: r = 10
  328.   (gdb) s 5                                             <- step over five lines
  329.   53                  r = m-1;
  330.   2: r = 10
  331.   1: l = 1
  332.   (gdb) p m*m                                           <- show expression
  333.   $1 = 25
  334.   (gdb) cont                                            <- continue program
  335.   Continuing.
  336.   4 primes                                              <- output of program
  337.  
  338.  
  339.   Program exited normally.
  340.   (gdb) q                                               <- quit gdb
  341.  
  342.   [D:\EMX\TEST]
  343.  
  344.  
  345. Viewing OS/2 .inf files
  346. -----------------------
  347.  
  348. If you've installed the optional emxview.zip and gnuview.zip packages,
  349. you can use the OS/2 VIEW utility to view a hypertext version of
  350. emxdev.doc, libref.doc, gnudev.doc and bsddev.doc.  If you've added
  351. c:\emx\book to the BOOKSHELF environment variable and defined the
  352. EMXBOOK environment variable (see above), type
  353.  
  354.     view emxbook
  355.  
  356. to view the concatenated .inf files.  To get help for, say, printf(),
  357. type
  358.  
  359.     view emxbook printf
  360.  
  361. If you haven't set the environment variables, type
  362.  
  363.     view c:\emx\book\emxdev
  364.  
  365. to view emxdev.inf.
  366.  
  367. If you've properly set the HELPNDX and DPATH environment variables,
  368. you can use the kwhelp (Ctrl-H) command of EPM to get on-line help for
  369. the function at the cursor.  With emxbook.ndx, all three books are
  370. required to be installed.  If you haven't installed all the books, use
  371. a subset of emxdev.ndx, libref.ndx, gnudev.ndx and bsddev.ndx in the
  372. HELPNDX environment variable.
  373.  
  374. emxbook.ndx contains all entries of emxdev.ndx, libref.ndx, gnudev.ndx
  375. and bsddev.ndx, pointing to `emxbook'.  Setting the EMXBOOK
  376. environment variable as explained above causes the three books to be
  377. concatenated and named `emxbook'.
  378.  
  379.  
  380. Viewing the GNU on-line manuals
  381. -------------------------------
  382.  
  383. To view the GCC, GDB, etc. manuals, unpack gnudoc.zip and gnuinfo.zip
  384. and install info (see install.doc).  Use GNU makeinfo to create info
  385. files for on-line help from the texinfo files.  makeinf.bat and
  386. makeinf.cmd are batch files which simplify calling makeinfo.
  387.  
  388. To create info files for the GCC manual, type:
  389.  
  390.   cd \emx\gnu\doc
  391.   makeinf gcc                   (Using and Porting GNU CC)
  392.   makeinf cpp                   (The C Preprocessor)
  393.   makeinf gxxint                (Internal Architecture of the Compiler)
  394.   makeinf reno                  (The GNU C++ Renovation Project)
  395.  
  396. To create info files for GDB, type:
  397.  
  398.   cd \emx\gnu\doc
  399.   makeinf gdb                   (Debugging with GDB)
  400.   makeinf gdbint                (The GNU debugger's internals)
  401.  
  402. To create info files for GAS, type:
  403.  
  404.   cd \emx\gnu\doc
  405.   makeinf as                    (The GNU assembler)
  406.   makeinf gasp                  (The GNU Assembler Preprocessor)
  407.  
  408. To create info files for the texinfo manual, type:
  409.  
  410.   cd \emx\gnu\doc
  411.   makeinf texi                  (The documentation format for the GNU Project)
  412.   makeinf makeinfo              (The makeinfo program)
  413.  
  414. To create info files for libg++, type:
  415.  
  416.   cd \emx\gnu\doc
  417.   makeinf libgpp                (User's Guide to the GNU C++ Class Library)
  418.   makeinf iostream              (The GNU C++ Iostream Library)
  419.  
  420. After creating the info files, you can use GNU info (see gnudev.doc
  421. for details) or GNU Emacs to view the info files.
  422.  
  423.  
  424. Printing the GNU manuals
  425. ------------------------
  426.  
  427. To print the manuals, you have to unpack gnudoc.zip and gnuinfo.zip.
  428. Additionally, you have to install TeX.  Of course, I recommend emTeX,
  429. which can be used both under OS/2 and DOS.  emTeX is available for
  430. anonymous ftp on
  431.  
  432.   ftp.uni-stuttgart.de   [129.69.8.13]: /tex-archive/systems/msdos/emtex
  433.   ftp.tex.ac.uk        [134.151.44.19]: /tex-archive/systems/msdos/emtex
  434.   ftp.shsu.edu         [192.92.115.10]: /tex-archive/systems/msdos/emtex
  435.   ftp.informatik.tu-muenchen.de [131.159.0.198]: /pub/comp/os/os2/emTeX
  436.  
  437. Don't forget to fetch the files from the betatest subdirectory!
  438.  
  439. The following instructions assume that you are using emTeX (with
  440. emTeX386).
  441.  
  442. To typeset the GCC documentation, type
  443.  
  444.   cd \emx\gnu\doc
  445.   makedvi gcc
  446.  
  447. This creates the following files:
  448.  
  449.   cpp.dvi                       (The C Preprocessor)
  450.   gcc.dvi                       (Using and Porting GNU CC)
  451.   reno.dvi                      (The GNU C++ Renovation Project)
  452.  
  453. To typeset internal G++ documentation (you don't need this unless you
  454. want to hack G++), type
  455.  
  456.   cd \emx\gnu\doc
  457.   makedvi gxxint
  458.  
  459. To typeset the GDB documentation, type
  460.  
  461.   cd \emx\gnu\doc
  462.   makedvi gdb
  463.  
  464. This creates the following files:
  465.  
  466.   refcard.dvi                   (GDB Reference Card)
  467.   gdb.dvi                       (Debugging with GDB)
  468.  
  469. To typeset internal GDB documentation (you don't need this unless you
  470. want to hack GDB), type
  471.  
  472.   cd \emx\gnu\doc
  473.   makedvi gdbint
  474.  
  475. This create the following files:
  476.  
  477.   gdbint.dvi                    (The GNU debugger's internals)
  478.   stabs.dvi                     (The "stabs" debugging information format)
  479.  
  480. To typeset the GAS documentation, type
  481.  
  482.   cd \emx\gnu\doc
  483.   makedvi gas
  484.  
  485. This creates the following files:
  486.  
  487.   as.dvi                        (The GNU assembler)
  488.   gasp.dvi                      (The GNU Assembler Preprocessor)
  489.  
  490. To typeset the texinfo documentation, type
  491.  
  492.   cd \emx\gnu\doc
  493.   makedvi texinfo
  494.  
  495. This creates the following files:
  496.  
  497.   texi.dvi                      (The documentation format for the GNU Project)
  498.   makeinfo.dvi                  (The makeinfo program)
  499.  
  500. To typeset the libg++ and iostream documentation, type
  501.  
  502.   cd \emx\gnu\doc
  503.   makedvi libgpp
  504.   makedvi iostream
  505.  
  506. This creates the following files:
  507.  
  508.   libgpp.dvi                    (User's Guide to the GNU C++ Class Library)
  509.   iostream.dvi                  (The GNU C++ Iostream Library))
  510.  
  511. --------------------------- END OF INSTALL.DOC ------------------------------
  512.