File: libsbml-accessing.html

package info (click to toggle)
libsbml 5.10.0+dfsg-1
  • links: PTS, VCS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 141,800 kB
  • ctags: 98,793
  • sloc: cpp: 804,405; xml: 206,907; ansic: 66,144; cs: 52,916; java: 25,093; python: 23,449; sh: 9,847; perl: 8,414; makefile: 7,580; ruby: 4,760; csh: 3
file content (535 lines) | stat: -rw-r--r-- 22,287 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
<p> Once the libSBML files are installed as described in the <a
href="libsbml-installation.html">installation instructions</a>, you may
need to do additional configuration steps so that software applications can
find the libSBML library files at <em>run</em> time.  This section provides
information about how to do that.

<ol>
 <li><a href="#common">Run-time environment configuration</a></li>
 <li><a href="#languages">Compiling software to use libSBML</a><br>
    <ul>
      <li><a href="#accessing-c">C++ and C</a></li>
      <li><a href="#accessing-java">Java</a></li>
      <li><a href="#accessing-python">Python</a></li>
      <li><a href="#accessing-matlab">MATLAB</a></li>
      <li><a href="#accessing-csharp">C#</a></li>
      <li><a href="#accessing-ruby">Ruby</a></li>
      <li><a href="#accessing-perl">Perl</a></li>
      <li><a href="#accessing-octave">Octave</a></li>
    </ul>
  </li>
</ol>


<h2><a class="anchor" name="common">1. Run-time environment configuration</a></h2>

<p>
Whether you downloaded a ready-built libSBML installation, or you followed
the <a href="libsbml-installation.html">installation instructions</a>,
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
<em>find</em> those files when it runs.  The run-time environment must be
properly configured first.

<h3>On most Linux/Unix-based platforms:</h3

<p><em><b>Either do the following:</b></em>
<ul>
<li><i>Unless</i> using Mac&nbsp;OS&nbsp;X systems, run the program
<code>ldconfig</code> as user 'root'.  (Please consult the man page for
<code>ldconfig</code> if this is unfamiliar.  On Mac&nbsp;OS&nbsp;X, there is no
equivalent to the <code>ldconfig</code> facility.)</li></ul>

<em><b>or do the following:</b></em>

<ul><li>Ensure that each user sets the environment variable
<code>LD_LIBRARY_PATH</code> in their command shells.  (On Mac&nbsp;OS&nbsp;X,
the variable is named <code>DYLD_LIBRARY_PATH</code>.)  The value of
<code>LD_LIBRARY_PATH</code> or <code>DYLD_LIBRARY_PATH</code> must include
the directory <span class="placeholder">DIR</span> used as the value of the
<nobr><code>--prefix=</code><span class="placeholder">DIR</span></nobr>
option used during the <a href="libsbml-installation.html">libSBML
configuration step</a>.  For example, suppose that you configured
libSBML to use the default installation prefix
<code><nobr>/usr/local/</nobr></code>.  Then in csh-based command shells
under Linux, if the <code>ldconfig</code> step is not performed, you may
have to set the variable as follows (perhaps in your <code>.cshrc</code>
file):

<pre class="fragment">
setenv LD_LIBRARY_PATH /usr/local/lib
</pre>

On Mac OS X, this would instead be

<pre class="fragment">
setenv DYLD_LIBRARY_PATH /usr/local/lib
</pre>


</li></ul>


<h3>On Microsoft Windows platforms:</h3>

<p>Set the <code>PATH</code> environment variable to include the
directory of the libSBML native library.  To set an environmental variable
in Windows, use the <em>System</em> option in the Windows <em>Control
Panel</em>.
</dd>
</dt>
</dl>

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



<h2><a class="anchor" name="languages">2. Compiling software to use
libSBML</a></h2>

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.


<h3><a class="anchor" name="accessing-c">C++
and C</a></h3>

<p> 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:
<ul>
<li> The flag <nobr><code>-I</code><span class="placeholder">DIR</span><code>/include</code></nobr> needs
to be supplied to the compiler, where <span class="placeholder">DIR</span> is the value of
the <nobr><code>--prefix=</code><span class="placeholder">DIR</span></nobr> option given during
configuration of libSBML.  In addition, it may be necessary to supply
a second <nobr><code>-I</code></nobr> 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 <code>/usr/local</code>, then when compiling your software
to use libSBML, you will also need to add the flag
<nobr><code>-I/usr/local/include</code></nobr>.

<p>

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

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

<pre class="fragment">
g++ `pkg-config --cflags --libs libsbml` myprogram.cpp
</pre>

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


<h3><a class="anchor" name="accessing-java">Java</a></h3>

<p> 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
<nobr><code>--with-java</code></nobr> flag as described in the <a
href="libsbml-installation.html">installation instructions</a>.

<p> The Java interface for libSBML is implemented partly as pure Java and
partly as Java Native Interface (JNI) code.  Once libSBML is configured and
built using the <nobr><code>--with-java</code></nobr> flag described above,
and libSBML has been installed on a computer, three more steps are required
to use the Java-libSBML interface in an application.


<h4>Step 1: set LD_LIBRARY_PATH (Linux), DYLD_LIBRARY_PATH
(Mac&nbsp;OS&nbsp;X), or PATH (Windows)</h4>

First, please follow the instructions for configuring the
<code>LD_LIBRARY_PATH</code> (under Linux, Unix, Cygwin),
<code>DYLD_LIBRARY_PATH</code> (under Mac&nbsp;OS&nbsp;X) or <code>PATH</code> (under
Windows) variables described in the beginning of this section.  This is
necessary so that, before the operating system starts a Java application,
the system loaders can find libSBML's native library components.


<h4>Step 2: adjust the application's class search path</h4>

Java applications separately need to have their class search paths include
the libSBML <code>.jar</code> and binary object files.  This is often most
easily done by setting the <code>CLASSPATH</code> environment variable, but
other methods are possible.  The exact recipe also depends on the operating
system in use, as follows:

<ul>

<li><em>Java on Linux, Mac&nbsp;OS X and similar Unix-like systems:</em>

<p> You must either (1) set your <code>CLASSPATH</code> environment
variable to include the <code>.jar</code> file, or (2) the file must be
listed in the <nobr><code>-classpath</code></nobr> 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
<code>/usr/local</code> (e.g., by using
<nobr><code>--prefix=/usr/local</code></nobr> when configuring libSBML),
the <code>libsbmlj.jar</code> file will end up as
<code>/usr/local/share/java/libsbmlj.jar</code> and your environment
variable would at minimum need to be set as follows:

<pre class="fragment">
  CLASSPATH=.:/usr/local/share/java/libsbmlj.jar
</pre>
</li>

<li><em>Java on Windows systems:</em>

<p> The instructions are essentially the same as for the case of Linux and
similar systems, although the syntax for setting environment variables is
slightly different.  For example, if you had installed libSBML into
<code>C:\libsbml</code> on your system, you might set your environment
variable as follows:

<pre class="fragment">
  CLASSPATH=.;C:\libsbml\libsbmlj.jar
</pre>

<p> Note: to set an environmental variable in Windows, use the
<em>System</em> option in the Control Panel.

</li>
</ul>


<h4>Step 3: load the libSBML JNI library in the application</h4>

Finally, because of how JNI works in Java, an explicit call to
<code>System.loadLibrary</code> is needed in an application to load the
native language library portion of libSBML.  This involves putting a Java
<code>static</code> somewhere in your application, usually in the
application's main class.  The following example illustrates one way of
doing this.

<pre class="fragment"><span style="color: #777">import org.sbml.libsbml.*;

public class YourMainApplicationClass
{
  public static void main (String[] args)
  {
    /* Whatever your application does here ... */
  }
</span>
  /**
   * The following static block is needed in order to load the
   * libSBML Java interface library when the application starts.
   */
  static
  {
    String varname;
    String shlibname;

    if (System.getProperty("os.name").startsWith("Mac OS"))
    {
      varname = "DYLD_LIBRARY_PATH";    // We're on a Mac.
      shlibname = "libsbmlj.jnilib and/or libsbml.dylib";
    }
    else
    {
      varname = "LD_LIBRARY_PATH";      // We're not on a Mac.
      shlibname = "libsbmlj.so and/or libsbml.so";
    }

    try
    {
      System.loadLibrary("sbmlj");
      // For extra safety, check that the jar file is in the classpath.
      Class.forName("org.sbml.libsbml.libsbml");
    }
    catch (UnsatisfiedLinkError e)
    {
      System.err.println("Error encountered while attempting to load libSBML:");
      e.printStackTrace();
      System.err.println("Please check the value of your " + varname +
			 " environment variable and/or" +
                         " your 'java.library.path' system property" +
                         " (depending on which one you are using) to" +
                         " make sure it lists all the directories needed to" +
                         " find the " + shlibname + " library file and the" +
                         " libraries it depends upon (e.g., the XML parser).");
      System.exit(1);
    }
    catch (ClassNotFoundException e)
    {
      System.err.println("Error: unable to load the file 'libsbmlj.jar'." +
                         " It is likely that your -classpath command line " +
                         " setting or your CLASSPATH environment variable " +
                         " do not include the file 'libsbmlj.jar'.");
      System.exit(1);
    }
    catch (SecurityException e)
    {
      System.err.println("Error encountered while attempting to load libSBML:");
      e.printStackTrace();
      System.err.println("Could not load the libSBML library files due to a"+
                         " security exception.\n");
      System.exit(1);
    }
  }
<span style="color: #777">
}</span>
</pre>



<h3><a class="anchor" name="accessing-python">Python</a></h3>

<p> 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
<nobr><code>--with-python</code></nobr> flag as described in the <a
href="libsbml-installation.html">installation instructions</a>.

<p> Once that is done, and libSBML has been installed on your system, then
Python needs just one more thing to be informed where to find the libSBML
package: it needs the environment variable named <code>PYTHONPATH</code> to
be set.  If <em><span class="placeholder">DIR</span></em> is the value of the
<nobr><code>--prefix=</code><em><span
class="placeholder">DIR</span></em></nobr> option given during
configuration of libSBML and <em><span
class="placeholder">version</span></em> is the version of your copy of
Python, then the value of <code>PYTHONPATH</code> needs to be set as
follows on Ubuntu&nbsp;11 systems:

<pre class="fragment" style="font-size: 12px">
export PYTHONPATH=<u><em><span
class="placeholder">DIR</span></em></u>/lib/<u><em><span class="placeholder">version</span></em></u>/site-packages
</pre>

and as follows for other Linux systems:

<pre class="fragment" style="font-size: 12px">
export PYTHONPATH=<u><em><span
class="placeholder">DIR</span></em></u>/lib/<u><em><span class="placeholder">version</span></em></u>/dist-packages
</pre>

The above is for <i>sh</i>-based shells such as Bash; if you use
<i>csh</i>-based shells, then the appropriate syntax is instead

<pre class="fragment" style="font-size: 12px">
setenv PYTHONPATH  <u><em><span
class="placeholder">DIR</span></em></u>/lib/<u><em><span class="placeholder">version</span></em></u>/site-packages
</pre>

and 

<pre class="fragment" style="font-size: 12px">
setenv PYTHONPATH  <u><em><span
class="placeholder">DIR</span></em></u>/lib/<u><em><span class="placeholder">version</span></em></u>/dist-packages
</pre>

for Ubuntu&nbsp;11 and non-Ubuntu systems, respectively.  In other words,
the <code>PYTHONPATH</code> environment variable needs to be set to the
<nobr><code>site-packages</code></nobr> or
<nobr><code>dist-packages</code></nobr> (depending on the flavor of Linux)
directory path where the libSBML library has been installed.  Please see
the section titled "<a href="libsbml-installation.html#locations">Files
installed by libSBML, and their locations</a>" elsewhere in this manual for
more information about the files installed for libSBML.

<p> Once the <code>PYTHONPATH</code> variable has been set, you should be
able to start the Python interpreter and type the following command to
import the libSBML package for Python:

<pre class="fragment">
from libsbml import *
</pre>

<p>
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
privileges) reset the permissions yourself.


<h3><a class="anchor" name="accessing-matlab">MATLAB</a></h3>

<p> 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
<nobr><code>--with-matlab</code></nobr> flag as described in the <a
href="libsbml-installation.html">installation instructions</a>.

<h4>MATLAB on Linux, Mac&nbsp;OS X and similar Unix-like systems</h4>

<p> As with the other cases described above, the first configuration step
necessary for users is to make sure that their <code>LD_LIBRARY_PATH</code>
or <code>DYLD_LIBRARY_PATH</code> environment variable (see the <a
href="libsbml-installation.html#accessing">relevant section in the
installation instructions</a>) 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
<code>TranslateSBML</code>.<em>extension</em>,
<code>OutputSBML</code>.<em>extension</em> and
<code>CheckAndConvert.m</code> will have been placed.  These files
implement the MATLAB interface to libSBML.  The
<code>LD_LIBRARY_PATH</code>/<code>DYLD_LIBRARY_PATH</code> 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.)

<p class="warning">
Important: some versions of MATLAB produced for Linux include a version of
the stdc++ library that conflicts with the version provided by the operating 
system, causing a mystifying error when MATLAB tries to run or compile code
involving libSBML.  Please see the <a
href="libsbml-issues.html#matlab-linux">section in the <em>Known Issues</em>
document</a> for more information. </p>

<p> 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 <span class="placeholder">DIR</span> is the
directory where the libSBML shared library as well as
<code>TranslateSBML</code>.<em>extension</em>,
<code>OutputSBML</code>.<em>extension</em>, and
<code>CheckAndConvert.m</code> have been installed, then the following
MATLAB command must be executed:

<pre class="fragment">
addpath('<span class="placeholder">DIR</span>');
</pre>

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

<pre class="fragment">
addpath('/usr/local/lib');
</pre>

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


<h4>MATLAB on Windows systems</h4>

<p> 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.  You
should be able to start MATLAB at will, and be able to invoke functions
like <code>TranslateSBML</code> and <code>OutputSBML</code>.

<p> 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 on Windows, follow these simple steps:

<ol>

<li style="margin-bottom: 1em">Start MATLAB.

<li style="margin-bottom: 1em">Within MATLAB, change directory to the
directory in your libSBML source tree containing the MATLAB code.  This
directory will be <code><span
class="placeholder">libsbml</span>/src/bindings/matlab</code>, where
<code><span class="placeholder">libsbml</span></code> is the root of your
libSBML source directory on your computer.

<li style="margin-bottom: 1em">Execute <code>buildSBML</code> in MATLAB.

<li style="margin-bottom: 1em">Execute <code>installSBML</code> in MATLAB.

</ol>

After these steps, you should be able to invoke functions
such as <code>TranslateSBML</code> and <code>OutputSBML</code>.  These will
be accessible after you restart MATLAB and even when you are no longer in
the libSBML directory.



<h3><a class="anchor" name="accessing-csharp">C#</a></h3>

First, as mentioned for some of the other languages described on this page,
please be aware that libSBML by default only builds the C and C++ APIs.
To build the C# API as well, libSBML has to be configured with the
<nobr><code>--with-csharp</code></nobr> flag as described in the <a
href="libsbml-installation.html">installation instructions</a>.

<p> The C# interface for libSBML is implemented partly as pure C# and
partly as native code.  Once libSBML is configured and built using the
<nobr><code>--with-csharp</code></nobr> flag described above, and libSBML
has been installed on a computer, two more steps are required to use the
C#-libSBML interface in an application.

<h4>Step 1: set LD_LIBRARY_PATH (Linux), DYLD_LIBRARY_PATH
(Mac&nbsp;OS&nbsp;X), or PATH (Windows)</h4>

<p> First, please follow the instructions for configuring the
<code>LD_LIBRARY_PATH</code> (under Linux, Unix, Cygwin),
<code>DYLD_LIBRARY_PATH</code> (under Mac&nbsp;OS&nbsp;X) or <code>PATH</code> (under
Windows) variables described in the <a href="#common">beginning of this
section</a>.  This is necessary so that, before the operating system starts
a C# application, the system loaders can find libSBML's native library
components.

<h4>Step 2: place the managed library <code>libsbmlcsP.dll</code> into your
application's directory</h4>

<p> C# applications need to be compiled by referencing the managed library
<code>libsbmlcsP.dll</code>.  This will also copy this managed library into
the application's output directory.

<p> Once the managed library is referenced, and the native library can be
found in the <code>PATH</code> (or, on Windows systems, if it is in the
same directory as the executable), the C# bindings can be used in any .Net
language program by simply including the libSBML namespace.  The following
C# code fragment illustrates how to use the namespace:

<pre class="fragment">
using namespace libsbml;
</pre>


<h3><a class="anchor" name="accessing-ruby">Ruby</a></h3>

(Documentation unfinished.)


<h3><a class="anchor" name="accessing-octave">Octave</a></h3>

(Documentation unfinished.)


<h3><a class="anchor" name="accessing-perl">Perl</a></h3>

(Documentation unfinished.)