To get started

## 2.1 To get started

- Directories
- Definitions
- Compiling, linking and running on Unix/Linux
- Compiling, linking and running on Windows

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.

### 2.1.1 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.

### 2.1.2 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>

### 2.1.3 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`.

### 2.1.4 Compiling, linking and running on Windows

If you use GCC, you can link either directly against `eclipse.dll` or against `eclipse.dll.a`. The required command line is similar to the Unix case.
If you use a Microsoft compiler, make sure you have the following additional settings 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:\Program Files\ECLiPSe 5.10\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:\Program Files\ECLiPSe 5.10\lib\i386_nt` as an additional library path.

Moreover, you need to create an `eclipse.lib` for the compiler to link against. This file can be created from `eclipse.def` and `eclipse.dll` (which are part of the ECLiPSe distribution), using the `lib.exe` or `link.exe` tool (which comes with the C/C++ development system).

        cd C:\Program Files\ECLiPSe 5.10\lib\i386_nt
        lib.exe /def:eclipse.def

Warnings about import directives can be ignored. If you do not have `lib.exe`, try instead

        link.exe /lib /def:eclipse.def

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`.