OS/2 Shareware BBS: 22 gnu/22-gnu.zip/epmgcc32.zip/INSTALL.DOC

Text File | 1996-12-07 | 13KB | 261 lines

              EPM 6.03 Interface to EMX/GCC, ICC, and other compilers

                             EPMGCC Version  3.20

                               Bernhard Bablok

                                December, 1996

Legal stuff:
~~~~~~~~~~~
See the file license.txt.


Requirements:
~~~~~~~~~~~~
The EMX/GCC interface to EPM supplied with this package needs to be compiled
before it can be incorporated into EPM. You will need to obtain the complete EPM
package (EPM 6.03 or above) from IBM to do this. The EPM package is available for
free from various Internet sites and is part of the Developer Connection CDs.

Note: EPM 5.51a is part of OS2 Warp (EPM 6.03b is part of Warp
      Version 4). You still need to obtain the complete package, since you
      need the source code of the standard set of e-macros.


Introduction:
~~~~~~~~~~~~
(Skip this section if you are familiar with configuring and compiling EPM).

To understand how the menu and function key support for EMX/GCC is implemented,
one has to understand how IBM's Enhanced Editor EPM works. EPM consists of one
exe-file (EPM.EXE) and a few "ex"-files, normally at least "epm.ex". EPM.EXE
supplies the PM-interface (e. g. message-queue), while the ex-files implement
the functions of the editor via compiled macros. Each ex-file is called a module
and consists of definitions of editor commands, internal procedures, menus, keys
and so on. These definitions are written in a macro language called "E", which
is similar but not identical to REXX. The source files have the extension "e".

Each module is the result of a compilation process of a source file. It is
possible to include other source files in a sort of "master source file".
Normally, the whole set of standard macros are compiled into one module, epm.ex.
This module is loaded at startup of the editor. Additional modules can be
loaded later.

Including source files into a master source file allows not only for an easier
maintenance of code, but allows the inclusion of files depending on
configuration constants (similar to #ifdef #include ... #endif structures in C).

Configuring EPM and adding own applications is made very simple through a trick.
The standard set of E-macros include a number of MY*.E files. These files are
the only ones which have to be changed. Once the MY*.E files are set up, only
epm.e have to be recompiled and the modules have to be located in a
place where the editor can find them.

The following sections deal with the installation of EPM 6.03b and the
modifications necessary on the MY*.E files to install EPMGCC.


Installation of EPM 6.0x:
~~~~~~~~~~~~~~~~~~~~~~~~
The EPM package includes two hypertext files; the EPM User's Manual, and the EPM
Technical Reference.  Both of these manuals provide a wealth of information on
EPM.  It is highly recommended that you spend some time becoming familiar with
EPM, and the E macro language by reading through them.

EPM consists of a number of *.exe-files (they belong somewhere along your PATH),
*.dll-files (they belong in a directory in your LIBPATH), *.hlp-files (put them
in a directory in your HELP environment variable) and *.inf-files (they should
go in a directory in your BOOKSHELF environment variable). That's it for the
basic installation. NOTE: make sure that all *.exe, *.dll etc. files come before
any files from the standard WARP EPM 5.51a distribution.

As mentioned above, most of the functionality of EPM is contained in macros.
All compiled macros (*.ex-files) must be either in the current directory,
in a directory along the PATH or EPMPATH, or in the directory of EPM.EXE (they
are searched in that order).

The macro translator ETPM.EXE will look for source files in the following
locations (in that order):
  - in the current directory
  - along the EPMPATH
  - along the DPATH
  - in the same directory as ETPM.EXE
e.g. if you enter the command `etpm epm`, then epm.e will be searched for in the
directories mentioned above.

I recommend the following setup:

  - don't put *.ex files into your EPMPATH, but somewhere along the PATH
  - copy all *.ex files except epm.ex (and draw.ex, see below) from the EPM 6.03
    package into one directory along your PATH
  - recompile draw.e if you do not set the constant WANT_DBCS_SUPPORT=1 in
    your mycnf.e
  - create the following directory structure

    e_macros               all my*.e files
       ├─ epmstd           all *.e files of the standard distribution
       ├─ epmbeta          all *.e files of epmbeta
       ├─ epmgcc           all files from EPMGCC
       ├─ tex              all files from the epmtex package (if needed)
       ├─ modified         all modified *.e files from the epmstd, epmbeta
       └─ other            various *.e files

  - setup your EPMPATH to contain all the above directories, make sure that
    e_macros\modified comes before e_macros\epmbeta and e_macros\epmstd. Of
    course you can add additional directories, depending on the number of
    packages you use.

Configuring the editor:
~~~~~~~~~~~~~~~~~~~~~~
"Configuring the editor" means the definition of constants which define the
behavior of the editor like colors, appearance of the mouse, mark-mode and (very
important!) which macros of the standard set are included into the base-module
epm.ex. Configuring is not only important to make EPM look and act like you
expect it to do, but also to save space. For example, I have thrown out all
macros which implement the host support, since my PC is not connected to a host.
This minimizes the startup time of the editor.

Configuration is done by setting up a file called MYCNF.E. This file is included
by various e-macro source file to alter the code at compile time.

Read the section in the EPM user's manual 'Changing the default configuration'
to understand the use of EPM's configuration constants and what they can do. The
binaries included with the EPM package were compiled with the constants defined
in epmgcnf.smp in your e_macros\epmstd subdirectory. If these are OK with you,
copy epmgcnf.smp to a file called mycnf.e in your e_macros directory. I have
also included a file MYCNF.SMP as an example of a configuration file (it is the
one I use).

Important notes: 1) Never put any executable e-code in MYCNF.E!
                 2) Configuriation for EPM 6.0x should be a bit different from
                    the configuration for EPM 5.51. See MYCNF.SMP for an example.
                 3) Please don't just copy MYCNF.SMP to MYCNF.E and then write
                    mails to me asking why EPM suddenly behaves different.


Implementing EPMGCC:
~~~~~~~~~~~~~~~~~~~
Any additional applications should be implemented via the MY*.E files. They are
included automatically at the right place. The following files are supplied as
samples (extension "smp" instead as "e"):

MYKEYS.E    This file should include application key definitions. It is better
            to use "TRYINCLUDE" statements, so you don't have to change this
            file if a new version of an application is to be used. The sample
            file consists of a single statement:
                 TRYINCLUDE 'gcckeys.e'.
            The included file defines some accelerator keys and the
            "next-error-key".  If the defined keys conflict with key definitions
            of other applications, you would have to edit gcckeys.e.

MYSTUFF.E   All includes for application macros which should go into the module
            epm.ex. The sample file consists of two statements (since I also use
            EPMTEX13):
                 TRYINCLUDE 'tex.e'
                 TRYINCLUDE 'gcc.e'
            If you do not have EPMTEX13, you do not have to remove the first
            line - it is ignored by the macro compiler.
            Important: none of the *parse.e and *set.e files should be
            included via TRYINCLUDE. They must be compiled separately!

MYMNUINI.E  This file is included by the standard macro which implements the
            menu support. If applications need menu support, their code should
            be included into this file. Again, the sample consists of two
            statements:
                 TRYINCLUDE 'texmenu.e'
                 TRYINCLUDE 'gccmenu.e'
            Note to EPMTEX13 users: I have renamed the file mymnuini.e supplied
            with EPMTEX13 to texmenu.e.

ACTIONS.LST This file is an exception. It is necessary for toolbar support and
            your actions.lst file must contain the line `gccactn`. The sample
            file provided in the distribution already contains this line.


Configuring EPMGCC:
~~~~~~~~~~~~~~~~~~
EPMGCC offers three levels of configuration. The basic configuration file
gccenv.e defines constants and defaults for various settings.

Configuration macros (provided are gccset.e, bccset.e, iccset.e, iccset2.e,
vacppset.e, vacppst2.e, ipfset.e, javaset.e, nrxset.e nrxset2.e) can be
used to define the utilities (compiler, make, debugger) which are invoked
by the various menu-selections and default values for the
compile/build-options.

Toggles for debug mode, autosave mode, verbose (test), the automatic removal of
error-files and save settings mode can be changed at runtime. They are saved
from session to session if save settings is checked.

A sample configuration file is included in the distribution (gccenv.smp).
Rename it to gccenv.e and change it to fit your needs.

Note that editing gccenv.smp is not enough, EPMGCC needs a file called
gccenv.e!


Compiling the macros:
~~~~~~~~~~~~~~~~~~~~
First, switch to the directory where you want to place your *.ex files. Then
invoke the command `makemacs` from the EPMGCC distribution. This batch file will
recompile epm.ex and all macros of EPMGCC. It writes a log called makemacs.log
and displays the log at the end. ETPM will complain about all errors with line
and column number. If all your paths are set up correctly and if MYCNF.E doesn't
contain errors, there should be no errors reported.

You should now be ready to use EPMGCC. For a test, start the editor, load a
c-source file into the edit-ring, edit it to include errors and press c-F12 (or
use the drop-down menu). After gcc has finished, press a-q once (this takes you
to the error-file) and after examining the errors press a-q again. This takes
you to the first error. Repeat pressing a-q to take you from error to error. At
any time, you can switch to the current error-file with the menu-selection "View
results" (there might be more than one error-file with the same name in the
edit-ring). If you want to go to a specific error, put the cursor on the line
reporting the error and press a-q.


Note on implicit and explicit linking of macros:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Compiled e-macros can be loaded implicitly and explicitly. The latter ones stay
in memory and are always available, e.g. epm.ex is loaded at startup of the
editor. You can use the command
    ql <module>  (e.g. ql epm)
to query the link status of a module.

The default configuration loads gccparse.ex, the gcc-error-parser at startup.

Implicit loading occurs when you issue a command from the editor command-line
(CTRL-i) and the command is not an internal command and is not found in the
set of explicitly loaded macros. EPM will then search your paths for a
compiled e-macro, load it into memory, execute and discard it. Candidates for
these kind of macros are either seldom used or big macros, which would
otherwise take away too much space.

The setup macros (e.g. gccset.e) will only work if they are implicitly loaded.
They perform three tasks: they set up some editor-variables, unload the
current error-parser and install a new one. Using this feature, you can switch
between compilers without quitting the editor and recompiling the macros.


Final notes:
~~~~~~~~~~~

I hope EPMGCC is of value for you.  If you think you have found a genuine bug,
or would like to make suggestions, contributions, or enhancements to this code
please drop me a note (I will include additional error-parsers in the
distribution, e.g. for texinfo, if I am provided with them).

Since I have released this code without charge, I cannot offer a warranty or
customer support, but I will do my best within the limit of available time.

English is not my native language. Nevertheless, I hope the documentation is
clear enough to be of use. Everybody is welcome to supply a corrected version if
you feel it makes things clearer.


12/07/96
Bernhard Bablok
D-82256 Fuerstenfeldbruck, Germany
INTERNET: [e-mail]