BASIS Quick Start Guide Getting Started by Andreas Schuh, updated by Andrew Hundt 11/11/2013 Copyright ©2011 University of Pennsylvania. Copyright ©2013 Carnegie Mellon University.

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

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

Introduction First install BASIS on your system. Use the so-called “basisproject” command line tool to create a new empty project. Add some example source files and edit the build configuration files to build the executable and library files. Finally, build and test the example project. For a more detailed explanation of each step, have a look at the corresponding BASIS Tutorial.

Windows Users To follow the steps in this quick start guide, you need to have a Unix-like operating system. Linux 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 tutorial available for Windows users. Alternatively, you can install CygWin. This would also allow you to use the BASIS tools which are not available for native Windows.

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

Get a Copy of BASIS Download the source code of BASIS: mkdir -p ~/local/src cd ~/local/src git clone https://github.com/schuhschuh/cmake-basis.git 10/21/2011 Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.

Configure BASIS Before you can build BASIS, you need to configure it using CMake 2.8.4 or greater. Configure the build system using CMake: mkdir basis-build cd basis-build ccmake ../basis 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/2011 Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.

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

Install BASIS 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/2011 Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.

Set Up Environment Set 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/2011 Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.

Creating a New Project How do I create my own BASIS conforming project? 10/21/2011 Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.

Create a New Project 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 by using the project tool again: 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/2011 Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.

Website Links 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 website of SBIA at: http://www.rad.upenn.edu/sbia/software/basis/manual.html

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

Install Your Project 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. The Build and Installation How-to summarizes these steps. Build and install the (currently empty) project: mkdir ~/local/src/hellobasis-build cd ~/local/src/hellobasis-build cmake -D INSTALL_PREFIX=~/local ../hellobasis make 10/21/2011 Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.

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

Add Executable Target 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/2011 Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.

Change Properties 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/2011 Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.

src/CMakeLists.txt 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/2011 Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.

Test the Executable 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 Note: The symbolic link named helloworld is in ~/local/bin/ which is already in our search path for executables (PATH). 10/21/2011 Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.

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

Add Private Library 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/2011 Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.

Add Public Library 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/2011 Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.

Add Script Module 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/2011 Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.

The .in Suffix 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 @PROJECT_NAME@ 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/2011 Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.

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

You just finished your first BASIS Quick Start Guide! Congratulations 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.