OaScript CMake Quick Start Guide

From oacwiki
Jump to: navigation, search

Get started now developing EDA applications for OpenAccess using C#. This guide describes how to license, download and build the oaScript C# binding on Linux or Windows.

For instructions on how to build the Perl, Python, Ruby or Tcl on Linux, see the oaScript 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:

  • Perl, Python, Ruby and Tcl use the GNU Make build system, which is tested only on Linux
  • For C# the Windows platform is mandatory, it is built using the cross-platform CMake build system that works on both Linux and Windows.
  • For Python, the cross-platform CMake build system works both on Windows and Linux.

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.

Linux Build

C# programs run great on Linux using Mono in place of the Microsoft .NET framework. Mono comes with most Linux distributions and is probably already installed on your system.

Linux System Requirements

oasCSharp has successfully built with the following tool chain and subsystems:

  • 64 bit Fedora 11 and 14 kernel 2.6.30.10
  • x86_64 hardware with at least 4GB physical memory
  • Mono 2.4.3.1
  • CMake 2.8.4 build system (must use 2.8.4 or above)
  • Perl 5.12.3
  • gcc compiler in the version range 4.1.1 - 4.2.3. The Working Group uses mostly gcc 4.2.0.
  • OpenAccess 22.04p054. The CMake build system will look for the path to OpenAccess in the following places:
    • The value of the CMake cache variable OPENACCESS_ROOT. This is set using the CMake -DOPENACCESS_ROOT:STRING=/path/to/oa command line option
    • The value of the ROOT_OA environment variable. This variable similarly affects other OpenAccess tools.
    • If /path/to/oa/bin is in the shell PATH, OpenAccess will be considered to be in /path/to/oa. This is perhaps the most convenient approach.
  • SWIG 2.0.1
  • NUnit 2.4.8. NUnit is included with Mono. On Fedora and SUSE, this is package mono-nunit

Unpack and Test the bin Package on Linux

To use the bin package, simply extract it,

 tar xvfz ~/Download/oaScript-0.8.0-cmake-rhel40-bin.tar.gz

Test the package by running the netlist lab. Add both OpenAccess and oaScript to the library path:

 export LD_LIBRARY_PATH=/path/to/oa-22.04p054/lib/linux_rhel40_64/opt:/path/to/oaScript-0.8.0/lib/linux_rhel40_64/opt

Run the compiled netlist lab under Mono:

 cd /path/to/oaScript-0.8.0
 mono lib/linux_rhel40_64/opt/netlistLabTest.exe examples/oaScript/csharp3.0/labs/netlist/Solution/gold.out

If the test succeeds, it will print,

 The test completed successfully.

and you are ready to develop applications as described in CSharp Language Binding for OpenAccess.

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

Build the wrappers or src Packages on Linux

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

Unpack the Downloaded Files

Start the build process by unpacking the src package that you downloaded earlier. For example:

 tar xvfz ~/Download/oaScript-0.8.0-cmake-src.tar.gz

Only if you want to build using the generated code in the wrappers package, unpack it. For example:

 tar xvfz ~/Download/oaScript-0.8.0-cmake-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-0.8.0

Create a Build Directory

With CMake it is recommended that you build in a directory other than the source tree (a new directory within the source tree is fine). In the wrappers package, this directory already exists. For the src package, create a directory. For example:

 mkdir Release    # Your choice of name.  Already done in the wrappers package.

cd into the build directory. For example:

 cd  Release

Configure with CMake on Linux

Run CMake, specifying the directory containing CMakeLists.txt, which relative to the build directory is "..":

 cmake ..

This does basically the same thing as the familiar "./configure" script—it generates a GNU Make build system that builds an optimized version of oaScript that will install into /usr/local/oaScript-version. OpenAccess is found via the PATH environment variable.

Other Ways to Configure with CMake

If you are satisfied with the basic configuration created with cmake .., you can skip ahead to the next section. This section illustrates how to configure different builds.

Use the CMake variable OPENACCESS_ROOT to directly specify the location of OpenAccess:

 cmake -DOPENACCESS_ROOT=/home/voom/src/oa-22.04p054 ..

You can create another directory and build debug code in it:

 cd ..
 mkdir Debug    # Your choice of directory name
 cd Debug
 cmake -DCMAKE_BUILD_TYPE:STRING=Debug ..

To prepare to install in a location other than the default /usr/local/oaScript-version:

 cmake -DCMAKE_INSTALL_PREFIX:PATH=/home/voom/oaScriptTrialInstall ..

Of course you can specify all the options at once. For example,

 cmake -DCMAKE_INSTALL_PREFIX:PATH=/home/voom/oaScriptTrialInstall \
       -DCMAKE_BUILD_TYPE=Debug \
       -DOPENACCESS_ROOT=/home/voom/src/oa-22.04p054  ..

The first time you run CMake, it caches the values of variables that take time to compute in the file CMakeCache.txt, and uses these values on subsequent runs. OPENACCESS_ROOT is one such variable. Therefore, if you run CMake with OPENACCES_ROOT=/home/voom/src/oa-22.04p028, and then you change your mind and want to run CMake with OPENACCES_ROOT=/home/voom/src/oa-22.04p054, you must either edit or delete CMakeCache.txt. See the documentation on running CMake for details.

Build with GNU Make

CMake created a Makefile for you, so build using GNU Make:

 make

Now you are ready to #Test oaScript and #Install oaScript as described toward the end of this guide.

How to Clean with GNU Make

As is customary with any build system, there is a clean target that you can optionally use to reset the build. C# compilation works fine in CMake, but the build system that CMake creates does not properly clean the C# source files csharp3.0/*.cs. Therefore to clean and restart the build:

 make clean
 rm csharp3.0/*.cs
 make

Of course, make clean removes the wrapper package files, but you can recover them by simply repeating the extraction of the wrapper package.

If you want to rebuild only a certain module, delete the C++ wrapper file for it:

 rm baseCSHARP_wrap.cxx
 make

Windows Build for C#

The OpenAccess C# binding supports Microsoft .NET framework 3.5 so it is a natural fit for Windows based EDA applications.

Windows System Requirements

oasCSharp has successfully built with the following tool chain and subsystems:

Unpack and Test the bin Package on Windows

To use the bin package, simply extract the downloaded file using Right Click > Extract All.

In a command window, change to the directory in which you installed oaScript, and run the compiled netlist lab:

 cd "c:\Program Files\oaScript-0.8.0"
 bin\win32\opt\netlistLabTest.exe examples\oaScript\csharp3.0\labs\netlist\Solution\gold.out 

If the test succeeds, it will print,

 The test completed successfully.

and you are ready to develop applications as described in CSharp Language Binding for OpenAccess.

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

Build the wrappers or src Packages on Windows

To build oaScript from source code using the src package, download the src and tu packages and extract them into the same folder with a tool like 7-Zip. The forthcoming discussion presumes that the downloads reside in folder:

 C:\Documents and Settings\johnm\My Documents\Visual Studio 2008\Projects\oaScript-0.8.0

To build the wrappers package, download the src and wrappers packages and extract them into the same folder (the wrappers package includes the tu package).

Prepare Your Environment

OpenAccess, SwigWin, and GnuWin32 do not come with Windows installers, so manually add their paths to the Path environment variable:

  • From the Start menu, open My Computer
  • Click on View System Information
  • Select the Advanced tab, click Environment Variables
  • In the Environment Variables form, select the Path variable and click Edit
  • Append the paths to OpenAccess executables and SWIG, separated by semicolons. For example, (all on the same line):
   existingPathContents;
   C:\Program Files\swigwin-1.3.36;
   C:\Program Files\oa-22.04p054\bin\win32\opt;
   C:\gnuwin32\bin
  • Dismiss all forms by clicking OK

Build on Windows

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 OpenAccess API parse tree file tu.cc.tu is created by GCC. To relieve you of having to install just the right version of GCC on Windows, tu.cc.tu is provided in the tu and wrappers packages. Therefore on Windows you always skip the first step in the build flow.

Launch a Visual Studio Command Prompt:

Start > All Programs > Microsoft Visual Studio 2008 > Visual Studio Tools > Visual Studio 2008 Command Prompt

This command prompt's environment is set up for the Visual Studio tools.

Change to the Release folder within the package file hierarchy:

 cd "C:\Documents and Settings\johnm\My Documents\Visual Studio 2008\Projects\oaScript-0.8.0\Release"

Configure with CMake on Windows

CMake generates an NMake build system that you will use to build oaScript. Another tantalizing option is to generate a Visual Studio 2008 solution, but only NMake is discussed here.

Launch CMake from the Visual Studio Command Prompt (not the Start menu} by typing:

 cmake-gui    # With some installations, you must type the full path

A CMake GUI window will appear. You can also try the CMake console command cmake -G "NMake Makefiles" .., but this guide covers only the CMake GUI.

In the CMake window, set Where is the source code to the place where you downloaded the oaScript source code. For example:

 C:/Documents and Settings/johnm/My Documents/Visual Studio 2008/Projects/oaScript-0.8.0

With CMake it is recommended that you build in a folder other than the source tree (a new folder within the source tree is fine). Set Where to build the binaries to:

 C:/Documents and Settings/johnm/My Documents/Visual Studio 2008/Projects/oaScript-0.8.0/Release

Press the Configure button:

  • CMake will ask you what generator (build system) to use. Specify NMAKE Makefiles. Only NMake will be explained here, but Visual Studio 9 2008 also works. Click Finish. The CMake GUI will look like this:
Oascript-cmake-configured-red.png

Edit the CMake variables in the Name/Value pane of the CMake window:

  • You probably want to build an optimized release, so the default of CMAKE_BUILD_TYPE is Release For a debugging build, set it to Debug. See the documentation on the CMake CMAKE_BUILD_TYPE variable for details.
  • Variables showing the type of build and the locations of the prerequisite software, like SWIG and OpenAccess, will also be displayed. Change these if you want something different.
  • If you will be installing oaScript in a location other than C:\Program Files\oaScript-version, set CMAKE_INSTALL_PREFIX to that path

Press the Configure button. If any of the variables remain highlighted in red, press the Configure button again, and repeat until no variables are red. When you are done, CMake will display the message,

 Configuring done 

Press the Generate button. This creates a hierarchy of NMake Makefiles in the Release\ folder.

Build with NMake

Return to the Visual Studio Command Prompt. Change your working directory to the Where to build the binaries folder. For example:

 cd %HOMEPATH%
 cd "My Documents\Visual Studio 2008\Projects\oaScript-0.8.0\Release"

CMake created an NMake Makefile for you, so build using nmake:

 nmake

Now you are ready to #Test oaScript and #Install oaScript as described below.

How to Clean with NMake

C# compilation works fine in CMake, but the build system that CMake creates does not properly clean the C# source files csharp3.0/*.cs. Therefore to clean and restart the build:

 nmake clean
 del csharp3.0\*.cs
 nmake

If you want to rebuild only a certain module, delete the C++ wrapper file for it:

 del baseCSHARP_wrap.cxx
 nmake

Build for Python using CMake (Linux/Windows)

--Mfiers@imec.be (talk) 04:15, 17 February 2014 (CST)

The CMake system has been extended from #Windows Build for C# to work with Python, both on Linux and Windows. This build system is tested with OA version oa22.41p004, CMake version 2.8.11.2. It has been reported working on a 64-bit Linux system, 32-bit Windows (using VC++ 2005) and 64-bit Windows (using VC++ 2010).

First we summarize the steps in short, then we detail the steps.

  • Prerequisites: installing CMake, VC++ 2005 (32-bit) / VC++ 2010 (64-bit).
  • Run cmake from the build directory. Make sure OA_ROOT is set (to the location of the OpenAccess, i.e. oaVersions\oa22.41p004). Choose to generate project for the correct VC++ version.
  • Open the solution in VC++ and build the solution.
  • Copy the generated files to the correct location.

The rest of this build is explained for the 64-bit Windows case. The 32-bit case is very similar, except of course that you should install a different Python version, and use the correct C++ compiler. On Linux, there's no cmake-gui, but you can use ccmake, which works very similar.

Prerequisites

Installing CMake

Any version later than 2.8.11 is good. Windows has an installer (http://www.cmake.org/cmake/resources/software.html).

Installing Perl

Strawberry Perl (http://strawberryperl.com/), version 5.18, 64-bit, was used.

Installing the VC++ compiler on Windows

Finding the correct compiler with all headers included can be difficult.

  • 32-bit oaScript build: we used the VC++ 2005 express edition, which has an on-line installer located at the following address:

http://go.microsoft.com/fwlink/?LinkId=51410&clcid=0x409. We used VC++ 2005 because the OA binaries included with oa22.41p004 are built using VC++ 2005.

  • 64-bit oaScript build: we used the VC++ 2010 professional edition. It should work with a free VC++ 2010 express (http://www.visualstudio.com/en-us/downloads#d-2010-express), after installing VC++ 2010 Service Pack 1 + Windows SDK. The Service Pack is necessary, otherwise CMake cannot recognize the compiler easily. The SDK is necessary for additional header files. For some reason the installation for the Windows SDK failed on my laptop. If anyone can successfully compile it, please adjust the Wiki.

For generating the TU files, normally, GCC 4.2 is necessary. For this build, we copied the generated TU file from Linux. To further automate the build, we can include a GCC 4.2 MinGW compiler, in order to generate the TU files. This is not yet added to the CMake system.

Running cmake

Invoking cmake-gui for the first time

Cmake has to be run from the root build directory. When creating an out-of-source build, swig is confused (because it doesn't find certain headers / .i files), and it doesn't warn you about them. So it's very dangerous and can lead to generate wrong binaries.

Before running CMake, make sure the ROOT_OA environmental variable is set, so that CMake can find the OpenAccess libraries. Then fire up the cmake-gui and press configure:

 cd path\to\oascript\trunk
 set ROOT_OA=C:\Users\mfiers\workspace\oa-sp\oaVersions\oa22.41p004
 cmake-gui -D CMAKE_BUILD_TYPE=Release .

Cmake gui configure.png

Note that you can choose a debug build too by changing the initial line:

 cmake-gui -D CMAKE_BUILD_TYPE=Debug .

The release type cannot be changed anymore afther the CMake cache has been made! So you have to delete the cache (CMakeCache.txt) and re-run from the command-line if you wish to change build type. This ensures the correct OA libraries are used for Release / Debug. The CMake system has not yet been tested using Debug.


Generating the solution

When clicking Finish, an initial solution will be generated which can be opened in Visual Studio. The initial generation checks for all compilers, whether perl is found, looks for the OA libraries etc. The result should look like below:


Cmake gui setup.png

Make sure you double-check all paths. As you can see here, the python include libraries are correct for the 64-bit build, but CMake has found the wrong interpreter. PYTHON_EXECUTABLE should also point to the python 64-bit folder.

Open the solution in VC++ and press 'build'

In the trunk folder, there should now be a oaScript.sln file. After opening the solution, you can start building oaScript.

Build solution2.png

Copy the generated files to the correct location

  • trunk\lib\x64\opt --> copy to python2\oa\2.7\win64\opt
  • trunk\bin\x64\opt --> copy to python2\oa\2.7\win64\opt

Finally, the python2\oa folder should contain the oa DLL files, and the python2\oa\2.7\win64\opt folder should contain the exp, lib and pyd files for each OA component (i.e., _base.exp, _base.lib, _base.pyd), and the oasBase/oasTech dll, exp, and lib files.

After setting the PYTHONPATH to python2, you should be able to do

 set PYTHONPATH=%PYTHONPATH%;c:\path\to\oascript\python2
 python
 >>> import oa

Test oaScript

Run the unit tests,

 make  test            # Linux
 nmake test            # Windows

or build and run the unit tests all at once:

 make  all test        # Linux
 nmake all test        # Windows

Since you have not yet installed, at this point of course isInstalledTest fails. It's nice when the others pass:

 Running tests...
     ...
 1/8 Test #1: isInstalledTest ..................***Not Run   0.00 sec
     Start 2: oasCSharpBaseTest
 2/8 Test #2: oasCSharpBaseTest ................   Passed    4.92 sec
     Start 3: oasCSharpDesignTest
 3/8 Test #3: oasCSharpDesignTest ..............   Passed    3.34 sec
     Start 4: oasCSharpDMTest
 4/8 Test #4: oasCSharpDMTest ..................   Passed    3.11 sec
     Start 5: oasCSharpTechTest
 5/8 Test #5: oasCSharpTechTest ................   Passed    3.97 sec
     Start 6: oasCSharpUtilTest
 6/8 Test #6: oasCSharpUtilTest ................   Passed    2.23 sec
     Start 7: oasCSharpWaferTest
 7/8 Test #7: oasCSharpWaferTest ...............   Passed    2.81 sec
     Start 8: netlistLabTest
 8/8 Test #8: netlistLabTest ...................   Passed    1.00 sec
 
 88% tests passed, 1 tests failed out of 8

The output of make test tells you only whether the tests pass or fail. You can see the details in the test log file:

 less Testing/Temporary/LastTest.log    # Linux
 type Testing/Temporary/LastTest.log    # Windows

You can control the tests and see more output if you use the CTest test runner directly:

 cd csharp3.0/test
 ctest -V

Or you can run only the tests whose name matches "Design":

 ctest -V -R Design

Or run all tests except those whose name matches "isInstalled":

 ctest -V -E isInstalled

See csharp3.0/test/README.txt for more details about the current state of the unit tests.

Install oaScript

Install in CMAKE_INSTALL_PREFIX (/usr/local/oaScript-version by default):

 make  install         # Linux
 nmake install         # Windows

If you want to install somewhere other than /usr/local/oaScript-version, set variable CMAKE_INSTALL_PREFIX as explained above.

Test the installation:

 make  test            # Linux
 nmake test            # Windows

The isInstalledTest test should pass this time. Note that the other tests, like oasCSharpBaseTest do not test the installation—they still test your build just as they did before you installed.

Now you are ready to develop applications as described in CSharp Language Binding for OpenAccess.

Personal tools