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

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

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

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

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

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

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

8. Configure BASIS
Before you can build BASIS, you need to configure it using CMake 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.

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

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

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

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

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

14. 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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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