BASIS Quick Start Guide by Andreas Schuh

 Introduction  Installing BASIS  Creating a New Project  Installing Your Project  Adding Executables  Adding Libraries 10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.2

What is this quick start guide about? 10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.3

 In this quick start guide, you will first of all install BASIS in your system.  Then, you will use so-called project tool of BASIS to create a new project.  After you created a new and empty project, you will add some example source files and edit the build configuration files to build the executable and library files.  Finally, you will build and test the example project.  For a more detailed explanation of each step, have a look at the corresponding BASIS Tutorial.BASIS Tutorial 10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.4

 To follow the steps in this quick start guide, you need to have a Unix-like operating system. Specifically, we focus on Linux, but it has also been tested on Mac OS X.  Note that BASIS can also be installed and used on Windows. The tools for creating a new project and for automated software tests are, however, only available for Unix.  At the moment, there is no separate quick start guide available for Windows users.  Alternatively, you can install CygWin.CygWin  This would also allow you to use the BASIS tools which are not available for native Windows. 10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.5

How do I get BASIS installed on my system? 10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.6

 Download the source code of BASIS 0.1:  mkdir -p ~/local/src  cd ~/local/src  svn export basis /21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.7

 Before you can build BASIS, you need to configure it using CMake or greater.  Configure the build system using CMake:  mkdir basis-0.1-build  cd basis-0.1-build  ccmake../basis-0.1  Hit ‘c’ to configure the project.  Change INSTALL_PREFIX to ~/local.  Disable any of the BUILD_*_UTILITIES options depending on whether you have Python or Perl installed on your system and intend to use these languages.  Hit ‘g’ to generate the Makefiles. 10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.8

 CMake has generated Makefiles for GNU Make.  Therefore, the build is triggered by the make command:  make 10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.9

 To install BASIS, we “build” the install target:  make install  As a result, CMake copies the built files into the installation tree as specified by the INSTALL_PREFIX variable.  Additionally, BASIS may create some symbolic links on Unix systems if the INSTALL_LINKS option was set to ON during the configuration of BASIS. 10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.10

 Se the following environment variables:  setenv PATH " ~/local/bin:${PATH} "  setenv BASIS_EXAMPLE_DIR " ~/local/share/basis/example "  setenv HELLOBASIS_RSC_DIR " ${BASIS_EXAMPLE_DIR}/hellobasis "  Using BASH:  export PATH= " ~/local/bin:${PATH} "  export BASIS_EXAMPLE_DIR= " ~/local/share/basis/example "  export HELLOBASIS_RSC_DIR= " ${BASIS_EXAMPLE_DIR}/hellobasis " 10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.11

How do I create my own BASIS-conform project? 10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.12

 Create a new and empty project as follows:  basisproject --name HelloBasis --description " This is a BASIS project. " --root ~/local/src/hellobasis  The next command demonstrates that you can modify a previously created project using again the project tool:  basisproject --root ~/local/src/hellobasis --noexample --config-settings  Here we removed the example/ subdirectory and added some configuration file used by BASIS. These options could also have been given to the initial command above instead. 10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.13

10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.14  More details on the creation of a new BASIS project and its modification afterwards using the project tool of BASIS can be found on the Wiki of SBIA at:  To:_Managing_a_BASIS_Project To:_Managing_a_BASIS_Project

Fine, so how do I build and install this BASIS project? 10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.15

 The build and installation of this BASIS project is identical to the build and installation of BASIS itself.  In fact, all CMake-based projects are build this way. Therefore, the file INSTALL-basis.txt which is part of BASIS summarizes these steps. INSTALL-basis.txt  Build and install the (yet empty) project:  mkdir ~/local/src/hellobasis-build  cd ~/local/src/hellobasis-build  cmake -D INSTALL_PREFIX=~/local../hellobasis  make 10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.16

How do I get my executables build? 10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.17

 Copy the source file from the example to src/ :  cd ~/local/src/hellobasis  cp ${HELLOBASIS_RSC_DIR}/helloc++.cxx src/  Add the following line to src/CMakeLists.txt under the section “executable target(s)”:  basis_add_executable (helloc++.cxx)  Note: Alternatively, you can use the implementation of this example executable in Python, Perl, BASH or MATLAB.  In case of MATLAB, add also a dependency to MATLAB:  basisproject --root ~/local/src/hellobasis --use MATLAB 10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.18

 The name of the output file is given by the OUTPUT_NAME property.  The name of the symbolic link is given by the SYMLINK_NAME property.  To change these properties, add the following lines to the src/CMakeLists.txt (after basis_add_executable() ):  basis_set_target_properties (  helloc++  PROPERTIES  OUTPUT_NAME " hellobasis "  SYMLINK_NAME " helloworld "  )  Note: If you used another example, you need to replace helloc++ by the name of the source file you used excluding the extension. 10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.19

10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.20  To conclude, your src/CMakeLists.txt file should now contain CMake code similar to the following snippet:  basis_add_executable (helloc++.cxx)  basis_set_target_properties (  helloc++  PROPERTIES  OUTPUT_NAME " hellobasis "  SYMLINK_NAME " helloworld "  )

10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.21  Now build the executable and test it:  cd ~/local/src/hellobasis-build  make  bin/hellobasis  How is it going?  Note: As you configured the build system before using CMake, we only need to run GNU Make. CMake will recognize the change of src/CMakeLists.txt and reconfigure the build system automatically.  Install the executable and test it:  make install  helloworld  How is it going?  Note: The symbolic link named helloworld is in ~/local/bin/ which is already in our search path for executables (PATH).

How do I add libraries/modules to my project? 10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.22

10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.23  Copy the files from the example to src/ :  cd ~/local/src/hellobasis  cp ${HELLOBASIS_RSC_DIR}/foo.* src/  Add the following line to src/CMakeLists.txt (section “library target(s)”):  basis_add_library (foo.cxx)  Note: This is a library without public interface.

10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.24  Create the subdirectory tree for the public header files:  cd ~/local/src/hellobasis  basisproject --root. --include  Copy the files from the example:  cp ${HELLOBASIS_RSC_DIR}/bar.cxx src/  cp ${HELLOBASIS_RSC_DIR}/bar.h include/sbia/hellobasis/  Add the following line to src/CMakeLists.txt (section “library target(s)”):  basis_add_library (bar.cxx)  Note: This is a library with public interface as declared in bar.h.

10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.25  Another kind of libraries are modules written in a scripting language such as Perl.  Copy the module file to src/ :  cd ~/local/src/hellobasis  cp ${HELLOBASIS_RSC_DIR}/FooBar.pm.in src/  Add the following line to src/CMakeLists.txt (section “library target(s)” ):  basis_add_library (FooBar.pm)

10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.26  Note that some of these files have a.in file name suffix.  This suffix can be omitted in the basis_add_library() statement. It has however an impact on how this function treats this file.  The.in suffix indicates that the file is not usable as is, but contains patterns such as which BASIS should replace during the build of the module.  The substitution of these patterns is what we refer to as “building” script files.

10/21/2011Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.27  Now build the libraries:  cd ~/local/src/hellobasis-build  make  And install them:  make install

9/30/2011BASIS IntroductionCopyright (c) 2011 University of Pennsylvania. All rights reserved.28 You just finished your first BASIS Quick Start Guide! If this was not clear enough or you would like to know more, have a look at the corresponding BASIS Tutorial which gives more details about each of the steps described here.BASIS Tutorial