Once the libSBML files are installed as described in the installation instructions, you may need to do additional configuration steps so that software applications can find the libSBML library files at run time. This section provides information about how to do that.

1. Run-time environment configuration
2. Compiling software to use libSBML
   - C++ and C
   - Java
   - Python
   - MATLAB
   - Octave
   - Perl
   - C#
   - Ruby

## 1. Run-time environment configuration

Whether you downloaded a ready-built libSBML installation, or you followed the installation instructions, copies of the different libSBML files will end up in appropriate destination directories on your computer. However, this does not necessarily guarantee that a given software application will be able to find those files when it runs. The run-time environment must be properly configured first.

In particular, on most Linux/Unix-based platforms, you must perform one of the following two steps:

- (On Linux and Unix-based systems other than MacOS X.) Run the system program `ldconfig` as user 'root'. (Please consult the man page for `ldconfig` if this is unfamiliar. On MacOS X, there is no equivalent to the `ldconfig` facility.)

or

- Ensure that each user sets the environment variable `LD_LIBRARY_PATH` in their command shells. (On MacOS X, the variable is named `DYLD_LIBRARY_PATH`.) The value of `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH` must include the directory used as the value of the `--prefix=`DIR option used during the libSBML configuration step.

  For example, suppose that you configured libSBML to use the default installation prefix `/usr/local/`. Then in csh-based command shells under Linux, if the `ldconfig` step is not performed, you may have to set the variable as follows (perhaps in your `.cshrc` file):

      setenv LD_LIBRARY_PATH /usr/local/lib

If your run-time environment and the run-time environment for your software applications do not know to look in the installation directory for libSBML, programs that require libSBML will fail to run and report errors about being unable to find libSBML.

## 2. Compiling software to use libSBML

If you configured libSBML to provide additional language interfaces (such as Java, Python, etc.), then you may also need to perform the following steps to make the language bindings available to software on your computer.

### C++ and C

If libSBML has been configured normally, then compiling C++ or C software to use it is a matter of supplying certain compilation and linking options. There are two main sets of settings:

- The flag `-I` prefix`/include` needs to be supplied to the compiler, where prefix is the value of the `--prefix=`value option given during configuration of libSBML. In addition, it may be necessary to supply a second `-I` flag with the directory containing the include files of the XML parser being used by libSBML. For example, if you are using the Xerces XML parser and you compiled and installed Xerces in `/usr/local`, then when compiling your software to use libSBML, you will also need to add the flag `-I/usr/local/include`.

- The flags `-L` prefix`/lib -lsbml -lstdc++ -lm` need to be supplied to the compiler or linker, where prefix is again the value of the `--prefix=`value option given during configuration of libSBML. In addition, you may need to supply a corresponding `-L` flag value to tell the linker where to find the XML parser library being used by libSBML.

If you have the `pkg-config` utility, the steps above can be substantially simplified. First, make sure that your `PKG_CONFIG_PATH` environment variable includes the path to the directory prefix`/lib/pkgconfig` (which is the directory where the file `libsbml.pc` will be installed by libSBML's `make install` step). Then, you can run `pkg-config` with the `--cflags` and/or `--libs` flags in your compilation/linking command. Here is an example:

    g++ `pkg-config --cflags --libs libsbml` myprogram.cpp

Note the use of the backward quote in the shell command above; it has the effect of running the command `pkg-config --cflags --libs libsbml` and substituting in place the flags returned by the command.

### Java

First, note that by default, libSBML only builds the C and C++ APIs. To build the Java API as well, libSBML has to be configured with the `--with-java` flag as described in the installation instructions.

Once that is done, then in addition to the instructions for configuring the `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH` variables described in the beginning of this section, Java applications separately need to have their class search paths include the libSBML `.jar` and binary object files. This is often most easily done by setting the `CLASSPATH` environment variable, but other methods are possible. The exact recipe also depends on the operating system in use, as described in the following subsections.

#### Java on Linux, MacOS X and similar Unix-like systems

You must either (1) set your `CLASSPATH` environment variable to include the `.jar` file, or (2) the file must be listed in the `-classpath` option passed to the Java interpreter when it is started. As an example of the former approach, if you had configured libSBML to install itself into `/usr/local`, the `libsbmlj.jar` file will end up as `/usr/local/lib/libsbml.jar` and your environment variable would at minimum need to be set as follows:

      CLASSPATH=.:/usr/local/lib/libsbmlj.jar

#### Java on Windows systems

The instructions are essentially the same as for the case of Linux and similar systems, but the name of the `.jar` file is different on Windows systems: it is called `sbmlj.jar`. For example, if you had installed libSBML into `C:\libsbml` on your system, you might set your environment variable as follows:

      CLASSPATH=.;C:\libsbml\sbmlj.jar

Note: to set an environmental variable in Windows, use the System option in the Control Panel.

### Python

First, note that by default, libSBML only builds the C and C++ APIs. To build the Python API as well, libSBML has to be configured with the `--with-python` flag as described in the installation instructions.

Once that is done, then in addition to the instructions for configuring the `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH` variables described at the beginning of this section, Python needs another environment variable named `PYTHONPATH` to be set according to where the libSBML Python binaries have been installed. Unfortunately, this variable's value is confusing to set. On Unix-based systems at least, if DIR is the value of the `--prefix=`DIR option given during configuration of libSBML and version is the version of your copy of Python, then the value of `PYTHONPATH` needs to be set as follows:

`export PYTHONPATH=DIR/lib/version/site-packages/libsbml:DIR/lib/version/site-packages`
for sh-based shells such as Bash, or
`setenv PYTHONPATH DIR/lib/version/site-packages/libsbml:DIR/lib/version/site-packages`
for csh-based shells. What is crucial in both cases is that the two directories listed on the path are the directories containing the files `_libsbml.so` and `libsbml.py`. Please see the section titled "Files installed by libSBML, and their locations" elsewhere in this manual for more information about the files installed for libSBML.

Once both the library path environment variable and `PYTHONPATH` have been set, you should be able to start the Python interpreter and type the following command to import the libSBML package for Python:

    from libsbml import *

If Python produces an import error or a failure in linking a new module, it almost certainly means that the environment variables have not been set correctly. It may also mean that the read/write permissions of the installed library files or a directory in the hierarchy containing them are such that you are not allowed to access the files. In that case, please consult your systems administrator or (if you have administrator priviledges) reset the permissions yourself.

### MATLAB

First, note that by default, libSBML only builds the C and C++ APIs. To build the MATLAB API as well, libSBML has to be configured with the `--with-matlab` flag as described in the installation instructions.

#### MATLAB on Linux, MacOS X and similar Unix-like systems

As with the other cases described above, the first configuration step necessary for users is to make sure that their `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH` environment variable (see the relevant section in the installation instructions) is set to the directory where the libSBML shared library object is installed. When the MATLAB bindings are enabled in libSBML, this directory is also the same one where the additional files `TranslateSBML`.extension and `CheckAndConvert.m` will have been placed. These files implement the MATLAB interface to libSBML. The `LD_LIBRARY_PATH`/`DYLD_LIBRARY_PATH` environment variable must be set in the terminal shell from which MATLAB is started prior to starting MATLAB. (Otherwise, MATLAB itself will not "see" the value of the variable.)

An additional step is necessary in the MATLAB environment itself: adding the same directory to the list of directories that MATLAB searches to find functions. If DIR is the directory where the libSBML shared library as well as `TranslateSBML`.extension, and `CheckAndConvert.m` have been installed, then the following MATLAB command must be executed:

    addpath('DIR');

For example, suppose you are using an Intel-based MacOS X system and you have configured libSBML to install itself into `/usr/local`. Then the files `TranslateSBML.mexmaci` and `CheckAndConvert.m` will have been installed as `/usr/local/lib/TranslateSBML.mexmaci` and `/usr/local/lib/CheckAndConvert.m`. You will need to set your `DYLD_LIBRARY_PATH` environment variable to `/usr/local/lib`, and also execute the following command (or an equivalent) in MATLAB:

    addpath('/usr/local/lib');

(To save the trouble of having to type the command above each time you start MATLAB, you may wish to put it in your `startup.m` file (i.e., the file MATLAB uses for user initialization). Please refer to the MATLAB documentation for more information about `startup.m` and where it is located.)

#### MATLAB on Windows systems

Most Windows users will probably prefer to install libSBML using the self-extracting installer provided separately and available for downloading from the same servers as the libSBML source code distribution. The installer will take care of placing the MATLAB files in directories where MATLAB can find them. Nothing further needs to be done in that case.

If you are compiling and installing libSBML from the sources, or else want/need to install the MATLAB bindings directly from the libSBML source distribution, there are two possible approaches.

- You can start a regular Windows command shell. At the prompt, change the current directory to the directory where the libSBML MATLAB bindings files are located, namely libsbml/`src/bindings/matlab` with libsbml here standing in for the directory where you unzip'ed the source distribution archive. Then, execute the command `make.bat`.

      cd libsbml/src/bindings/matlab
      make.bat

  This script will start MATLAB, then run commands to install the bindings files and set up paths in your MATLAB environment so that MATLAB will find the files in future sessions.

- You can start MATLAB manually, then change directory to libsbml/`src/bindings/matlab`, and finally run the MATLAB script `install_Win32.m` located in that directory.

      cd libsbml/src/bindings/matlab;
      install_Win32;

  This will have the same effect as the previous alterantive

### Octave

(Documentation unfinished.)

### Perl

(Documentation unfinished.)

### C#

(Documentation unfinished.)

### Ruby

(Documentation unfinished.)