To get started

This section is about the prerequisites for working with ECLiPSe in your development environment. The directory structure, the libraries and the include files are described.

Directories

The libraries and include files needed to use ECLiPSe as an embedded component are available under the ECLiPSe directory which was set-up during installation. If you have access to a stand-alone ECLiPSe it can be found using the following query at the ECLiPSe prompt:

    [eclipse 1]: get_flag(installation_directory,Dir).

    Dir = "/usr/local/eclipse"
    yes.
    [eclipse 2]

We will assume from here that ECLiPSe was installed in "/usr/local/eclipse".

You would find the include files in "/usr/local/eclipse/include/$ARCH" and the the libraries in "/usr/local/eclipse/lib/$ARCH" where "$ARCH" is a string naming the architecture of your machine. This can be found using the following ECLiPSe query:

    [eclipse 2]: get_flag(hostarch,Arch).

    Arch = "sun4"
    yes.
    [eclipse 3]:

You will need to inform your C or C++ compiler and linker about these directories so that these tools can include and link the appropriate files. A make file "Makefile.external" can be found together with the libraries. The definitions in that makefile may have to be updated according to your operating system environment.

A set of example C and C++ programs can be found in "/usr/local/eclipse/doc/examples".

When delivering an application you will have to include with it the contents of the directory "/usr/local/eclipse/lib" without which ECLiPSe cannot work. Normally this would be copied into the directory structure of the delivered application. The interface can set different values for this directory, enabling different applications to have different sets of libraries.

Definitions

To include the definitions needed for calling the ECLiPSe library in a C program use:

    #include <eclipse.h>

For C++ a more convenient calling convention can be used based on some classes wrapped around these C definitions. To include these use:

    #include <eclipseclass.h>

Compiling, linking and running on Unix/Linux

Assuming that the environment variable ECLIPSEDIR is set to the ECLiPSe installation directory and the environment variable ARCH is set to the architecture/operating system name, an application can be built as follows:

gcc -I$ECLIPSEDIR/include/$ARCH eg_c_basic.c -L$ECLIPSEDIR/lib/$ARCH -leclipse

This will link your application with the shared library libeclipse.so.

At runtime, your application must be able to locate libeclipse.so. This can be achieved by adding ECLIPSEDIR/lib/ARCH to your LD_LIBRARY_PATH environment variable.

The embedded ECLiPSe finds its own support files (e.g. ECLiPSe libraries) through the ECLIPSEDIR environment variable. This must be set to the location where ECLiPSe is installed, e.g. /usr/local/eclipse. Alternatively, the application can invoke ec_set_option to specify the ECLIPSEDIR location before initialising the embedded ECLiPSe with ec_init.

Static linking (Unix/Linux)

If your operating system only supports static linking, or if you want to link statically for some reason, you have to link explicitly with libeclipse.a and the necessary support libraries must be specified, e.g.

gcc -I$ECLIPSEDIR/include/$ARCH eg_c_basic.c $ECLIPSEDIR/lib/$ARCH/libeclipse.a
    -L$ECLIPSEDIR/lib/$ARCH -lgmp -lshm -ldummies -ldl -lnsl -lsocket -lm

The libraries gmp, shm and dummies are ECLiPSe support libraries and must be specified in that order. The others are Unix libraries.

It is recommended that you copy the makefile "Makefile.external" provided in your installation directory under lib/$ARCH and adapt it for your purposes.

Compiling, linking and running on Windows

You need to have the following additional setting in your C/C++ compiler/development system:

• In the C/C++ Preprocessor settings, specify the ECLiPSe include directory as an additional include directory, e.g. C:/Eclipse/include/i386_nt.
• In the Link settings, specify eclipse.lib as an additional object/library module, and the location of this library, e.g. C:/Eclipse/lib/i386_nt as an additional library path.

At runtime, your application must be able to locate eclipse.dll, i.e. you should either

• copy eclipse.dll into the folder where your application is located, or
• copy eclipse.dll into one of Windows' standard library folders, or
• add the path to the folder where eclipse.dll can be found to your PATH environment variable.

The eclipse.dll finds its own support files (e.g. ECLiPSe libraries) through the ECLIPSEDIR registry entry under the registry key HKEY_LOCAL_MACHINE\SOFTWARE\IC-Parc\ECLiPSe\X.Y (X.Y is the version number). This must be set to the location where ECLiPSe is installed, e.g. C:/Eclipse. Alternatively, the application can invoke ec_set_option to specify the ECLIPSEDIR location before initialising the embedded ECLiPSe with ec_init.