To get started

2.1 To get started

This section is about the prerequisites for working with ECLⁱPS^e 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 ECLⁱPS^e as an embedded component are available under the ECLⁱPS^e directory which was set-up during installation. If you have access to a stand-alone ECLⁱPS^e it can be found using the following query at the ECLⁱPS^e prompt:

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

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

We will assume from here that ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e finds its own support files (e.g. ECLⁱPS^e libraries) through the ECLIPSEDIR environment variable. This must be set to the location where ECLⁱPS^e is installed, e.g. /usr/local/eclipse. Alternatively, the application can invoke ec_set_option to specify the ECLIPSEDIR location before initialising the embedded ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e 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. ECLⁱPS^e 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 ECLⁱPS^e is installed, e.g. C:/Eclipse. Alternatively, the application can invoke ec_set_option to specify the ECLIPSEDIR location before initialising the embedded ECLⁱPS^e with ec_init.