OaScript Quick Start Guide

From oacwiki
Jump to: navigation, search

Get started now developing EDA applications for OpenAccess with Perl, Python, Ruby or Tcl. This guide describes how to license, download and build these oaScript bindings on Linux.

For instructions on how to build the C# binding on Linux or Windows, see the oaScript CMake Quick Start Guide.

Contents

Before You Start

As explained in the OpenAccess Quick Start Guide, OpenAccess is licensed software. See Si2's OpenAccess License Information for instructions on what you need to do. Your legal department will need to approve this, so start this paperwork in advance.

Overview

The installation of oaScript involves two major steps:

  • Download and install OpenAccess as explained below
  • Download and install oaScript as explained below

oaScript uses two different build systems:

The C++ API documentation serves as the main documentation for oaScript. You can find it within the OpenAccess installation at doc/oa/html/index.html. The oaScript documentation here on the OpenAccess public wiki provides information on how the API for your scripting language differs from the C++ API.

Download and Install OpenAccess

Once you have your Si2.org user ID, download and install OpenAccess as instructed in the OpenAccess Quick Start Guide. Get version oa-22.04p054.

Download oaScript

While logged in with your Si2.org user ID, go to the oaScript project page. There you will find three types of packages to download.

The bin Package

This package contains pre-built binaries for oaScript. It is a best-effort attempt to be compatible with Red Hat Enterprise Linux 5 and common versions of the scripting languages. It can be used with the version oa-22.04p054 OpenAccess major release available from Si2.

Currently, the bin package is built for:

  • C# 3.0
  • Perl 5.8.x
  • Python 2.5.x
  • Ruby 1.8.x (Ruby 1.8.5+ is required on Red Hat Enterprise Linux 5 and SUSE Linux Enterprise Server 10)
  • Tcl 8.4.x

The bin package is built against OpenAccess 22.04p054, but is compatible with the incremental source releases that follow this major release.

The wrappers Package

The wrappers package contains prepared C wrapper source code files. In this partially built package, Si2 has already taken care of the tricky code generation steps. You will perform the final compilation steps on your system, so with the wrappers package you get the platform independence that you always get when you compile from source code. Use the wrappers package if you want to run oaScript on a platform other than Red Hat Enterprise Linux 5, or if you find the that the bin package is otherwise incompatible with your system.

However, since it is the code generation that makes oaScript independent of OpenAccess version, a wrappers package is tied to a single OpenAccess version.

The wrappers package requires the src package.

The src Package

This package contains the files necessary to generate and compile oaScript from scratch. It also contains the unit tests and laboratory exercises. If you want to build the bindings (even the wrappers package), run the unit tests, or run the labs, you need this package.

To avoid having to run the tricky TU parse tree extraction and SWIG code generation, you may prefer to utilize the wrappers package.

System Requirements

Currently, the oaScript GNU Make build system supports Perl, Python, Ruby and Tcl on Linux. The OaScript CMake build system supports C# on Linux and Windows.

It is recommended that you have at least 4GB of physical memory when you build oaScript.

The following software must be installed on your system:

  • The development package for the language you want to bind: Perl, Python, Ruby or Tcl
  • Perl version 5.6.0 or newer. Even if you are not building the oasPerl binding, the build system runs Perl scripts.
    • Perl module ExtUtils::Embed is required.
  • GCC compiler in the version range 4.1.1 - 4.2.3. The Working Group uses mostly gcc 4.2.0.
  • GNU Make version 3.81 or newer
  • SWIG version 1.3.34 or newer
  • The full set of OpenAccess source code and libraries, with the original directory structure intact

Unpack the bin Package

To use the bin package, simply extract it,

 tar xvfz ~/Download/oaScript-v0.7-2011.03.08-bin.tar.gz

and skip ahead to the #Using oaScript section.

If you are unable to use the binary package due to compatibility problems, try building the wrappers or src packages described below.

Build the wrappers or src Package

The diagram below shows the flow executed by the oaScript build system. The first two steps extract SWIG interface files (.i files) customized to the particular OpenAccess version that you are using. In the third step, SWIG generates the source code for the scripting language wrappers. In the final steps, the source code is compiled.

Oascript-build-flow.png

The wrappers package contains the source code files created by the first three steps, so all you need to do is compile them. This simplicity comes at the expense of OpenAccess version independence—each wrappers package targets a single OpenAccess version.

Start the build process by unpacking the source code that you downloaded earlier. For example:

 tar xvfz ~/Download/oaScript-v0.7-2011.03.08-src.tar.gz

If you are building the wrappers package, unpack it. For example:

 tar xvfz ~/Download/oaScript-v0.7-2011.03.08-wrappers.tar.gz
 

This wrappers package gives you the source code files that result from the code generation steps.

cd into the unpacked directory. For example:

 cd oaScript-v0.7-2011.03.08/

Create the file make.variables from the provided template:

 cp make.variables.template make.variables

Open make.variables in a text editor, and provide definitions for the variables at the top of the file. If you are using the wrappers package, you can ignore the SWIG and SWIGINC variables.

 gedit make.variables &

Compile. To make individual target languages, you may do any of the following:

 make perl
 make python
 make ruby
 make tcl

To make all target languages:

 make

If you have multiple processor cores and at least 5GB of physical memory available, you can use the make -j option to enable parallel builds:

 make -j 2

NOTE There will be a LOT of benign compiler warnings.

Test oaScript

To build all languages and run their unit tests:

 make all test

Do not use the -j option when running the tests because the tests for a single language must run serially.

The following directories contain test scripts for each target language:

 perl5/test/
 python2.5/test/
 ruby/test/
 tcl/test/

Within these directories, base_test may be run standalone with no arguments. dm_test requires a -libdefs libDefs argument, where -libdefs libDefs

Using oaScript

To use oaScript in your shell, you need to set some environment variables. The bash shell is assumed in the following examples.

Module Path for Your Language

Configure your environment by adding oaScript to the path for your language:

 export PYTHONPATH=${OASCRIPT_HOME}/python2.5:${PYTHONPATH}
 export PERL5LIB=${OASCRIPT_HOME}/perl5:${PERL5LIB}
 export TCLLIBPATH="${OASCRIPT_HOME}/tcl8.4/oa/x86_64 ${TCLLIBPATH}"
 export RUBYLIB=${OASCRIPT_HOME}/ruby1.8:${RUBYLIB}

Note that unlike the other variables, TCLLIBPATH is delimited by white space, not ':'.

where ${OASCRIPT_HOME} is the location of oaScript, such as:

 /home/OpenAccess/oaScript-v0.7-2011.03.08

LD_LIBRARY_PATH

Set LD_LIBRARY_PATH to include the OpenAccess libraries:

   export LD_LIBRARY_PATH=${OA_PATH}/lib/linux_rhel40_64/opt

Where ${OA_ROOT} is the location of OpenAccess.

However, setting LD_LIBRARY_PATH globally is evil. Ultimately you should use some other method such as a wrapper script or the GCC $ORIGIN option.

If you get an error like,

 OSError: /usr/lib64/libstdc++.so.6: version `GLIBCXX_3.4.9' not found (required by ${OA_ROOT}/lib/linux_rhel40_gcc423_64/opt/liboaCommon.so)

your system does not have the version of libstdc++ required by OpenAccess. The same thing can happen with oasPython. Generally it means that OpenAccess or oasPython was compiled using a newer version of GCC, and thus depends on a version of libstdc++ newer than you have installed.

There are a few solutions to this situation:

  • Install a version of GCC with version greater than or equal to the versions with which OpenAccess and oaScript were compiled. The GCC installation contains libstdc++. Add its path to LD_LIBRARY_PATH so the run time loader can find it. For example,
 export LD_LIBRARY_PATH=${GCC_ROOT}/4.5.2/linux64/lib64:${OA_ROOT}/lib/linux_rhel40_gcc423_64/opt

Within Your Language Interpreter

For details on how to load the bindings into your interpreter, refer to the documentation on your language:

Personal tools