BASIS Tutorial by Andreas Schuh Copyright ©2011 University of Pennsylvania. Copyright ©2013...

Getting StartedBASIS Tutorial

by Andreas Schuh

Copyright ©2011 University of Pennsylvania. Copyright ©2013 Carnegie Mellon University.

11/11/2013

Getting Started Copyright (c) 2011 University of Pennsylvania. All rights reserved.

2

Outline

Introduction

Installing BASIS

Creating a New Project

Installing Your Project

Adding Executables

Adding Libraries10/21/2011


3

IntroductionWhat is this tutorial about?

10/21/2011


4

Introduction

In this tutorial you will take the following steps: install BASIS on your system.

Use the “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.

10/21/2011

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.

http://www.cygwin.com/


6

Installing BASISHow do I get BASIS installed on my system?

10/21/2011


7

Prerequisites

CMake 2.8.4 + On Ubuntu 11.10, install cmake and cmake-curses-gui.

On previous Ubuntu versions and other Linux distributions, you need to download the latest CMake package from http://www.cmake.org/cmake/resources/ software.html

C++ compiler such as gcc or clang These are already part of the default installation of most Linux

distributions. On Ubuntu (and possibly others as well), you need to install the C++ compiler explicitly, i.e., the package g++.

Doxygen (optional) For generating html documentation

LaTeX For generating PDF documentation

Sphinx For generating documentation

10/21/2011

http://www.cmake.org/cmake/resources/software.html

http://www.cmake.org/cmake/resources/software.html

8

Download BASIS

The link to the git repository of BASIS is https://github.com/schuhschuh/cmake-basis

Development of BASIS follows the git-flow development pattern. http://nvie.com/posts/a-successful-git-branching-model/

Branches are named and utilized as follows: master

▪ most recent release

develop▪ main development branch with merged features for the next release

feature/*▪ feature branch with an individual feature that is under development

https://github.com/schuhschuh/cmake-basis

https://github.com/schuhschuh/cmake-basis

http://nvie.com/posts/a-successful-git-branching-model/

http://nvie.com/posts/a-successful-git-branching-model/

9

Download BASIS

In order to be able to easily update your copy of BASIS after minor bug fixes during this tutorial session, please check out a working copy of the BASIS 0.1 branch, i.e.,

mkdir -p ~/local/src cd ~/local/src git clone https://github.com/schuhschuh/cmake-basis.git

If you prefer a prefix other than ~/local/, you will need to substitute it here and in the remainder of this tutorial.

https://github.com/schuhschuh/cmake-basis.git







10

Build BASIS

For detailed build instructions, please have a look at the files INSTALL.txt and How To: Build and Install which you can also find in ~/local/src/basis/.

The particular build steps suggested for this tutorial can be found on the next slide.

10/21/2011

https://github.com/schuhschuh/cmake-basis/blob/master/INSTALL.txt

http://www.rad.upenn.edu/sbia/software/basis/howto/install.html


11

Build BASIS

Create an empty directory for the build tree: mkdir ~/local/src/basis-build cd ~/local/src/basis-build

Run CMake to configure the build system: ccmake ../basis Hit ‘c’ to trigger the configuration step of CMake Modify the CMake variables as follows:

▪ INSTALL_PREFIX ~/local

Hit ‘c’ until the ‘g’ option is available, then press ‘g’ to have CMake generate the Makefiles for GNU Make and exit.

Alternatively, you can also simply run the non-interactive command

cmake -D INSTALL_PREFIX=~/local ../basis Build the software using GNU Make:

make10/21/2011


12

Install BASIS

Run:

make install

During the installation, CMake will copy the built files into the installation tree at INSTALL_PREFIX and perform some more actions such as, for example, the creation of symbolic links on Unix (INSTALL_LINKS ON). More on this later on in this tutorial.

Note: For those familiar with CMake, you may notice that we useINSTALL_PREFIX instead of CMAKE_INSTALL_PREFIX.Both are equivalent and BASIS forces them to have the same

value.10/21/2011


13

Set Up Environment

Now that you have BASIS installed on your system, you should set up your environment for a more convenient use of the BASIS Tools as well as to help CMake find BASIS.

Therefore, add the bin/ directory of the BASIS installation to your PATH environment variable:

setenv PATH "${HOME}/local/bin:${PATH}"

Using BASH: export PATH="${HOME}/local/bin:${PATH}"

10/21/2011


14

Set Up Environment

In order to shorten the commands used throughout the tutorial, set also the following environment variables:

setenv BASIS_EXAMPLE_DIR "${HOME}/local/share/basis/example" setenv HELLOBASIS_RSC_DIR "${BASIS_EXAMPLE_DIR}/hellobasis"

Using BASH: export

BASIS_EXAMPLE_DIR="${HOME}/local/share/basis/example" export HELLOBASIS_RSC_DIR="${BASIS_EXAMPLE_DIR}/hellobasis"

10/21/2011


15

Creating a New ProjectHow do I create my own BASIS-conform project?

10/21/2011


16

The Project Tool

10/21/2011

The command-line tool basisproject is used to create a new BASIS project or to modify an existing one. This tool, also referred to as “project tool”, eases and automates the task of creating a new project.

As not all projects will make use of the same BASIS features, the project tool allows a selection of those features (i.e., directories and template files) relevant to your project.

See the help output of the project tool for details: basisproject --help basisproject --helpshort


17

The Project Tool

10/21/2011

The project tool needs to keep a copy of the original template files to be able to merge your changes of these files using diff3 with the current template files.

These copies are stored in the .basis/ subdirectory.

Commit the .basis/ subdirectory and any changes made to it by the project tool to the revision control system, i.e., Subversion (SVN) in our case.

Do not modify the files within the .basis/ subdirectory manually unless you know what you are doing!

For release versions of your software, you should remove the .basis/ subdirectory as it is no longer needed for this release.


18

Create a New Project

10/21/2011

To create a new empty project for this tutorial, enter the following command:

basisproject --name HelloBasis--description "A first BASIS project."--root ~/local/src/hellobasis

This creates the directory ~/local/src/hellobasis/ and populates the project by instantiating the standard project template of BASIS.


19

Modify the Project

10/21/2011

Once you created a BASIS project using the project tool, you can use it again to add or remove certain features of the project template as well as to add or remove dependencies on other software packages.

For demonstration, you should now remove the example/ subdirectory tree of your HelloBasis project and add the config/Settings.cmake file using the command:

basisproject --root ~/local/src/hellobasis--noexample --config-settings

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




21

Building Your ProjectFine, so how do I build this BASIS project?

10/21/2011


22

Building Your Project

10/21/2011

The build of any BASIS project is similar to the build of BASIS itself. The main steps are indeed identical for just any CMake-based project.

These common steps of creating a separate build directory, running CMake to configure the build system, and building the software, are described in the INSTALL-basis.txt document which is part of BASIS.

The only difference between BASIS projects will be the CMake variables that can be modified to configure the build.

https://sbia-svn.uphs.upenn.edu/projects/BASIS/branches/basis-0.1/doc/INSTALL-basis.txt


23

Build Your Project

10/21/2011

In order to build the (yet empty) HelloBasis project, do: mkdir ~/local/src/hellobasis-build cd ~/local/src/hellobasis-build ccmake ../hellobasis

Hit ‘c’ to configure the project. CMake should be able to find your BASIS intallation and set BASIS_DIR to ~/local/lib/cmake/basis. If not, you need to set this variable manually. Alternatively, you can set an environment variable named BASIS_DIR pointing to the directory containing the BASISConfig.cmake file.

Change the value of the CMake variable INSTALL_PREFIX to ~/local. Hit ‘g’ to generate the Makefiles.

make


24

Adding ExecutablesHow do I get my executables build?

10/21/2011


25

Executables

10/21/2011

Executables are either binary files built from C++ or MATLAB sources or script files interpreted by a command interpreter such as Python, Perl, or BASH.

We distinguish between two kinds of executables:

Main executables are supposed to be used by a user of our software directly. They parse command-line arguments and provide help and version information.

Auxiliary executables, on the other side, are only used by other executables.


26

How to Add Executables

10/21/2011

Copy the source files of your executable to the src/ subdirectory of your project. You can create further subdirectories within this directory if it helps to better organize your source files.

Edit the src/CMakeLists.txt file to add an executable build target which will build the executable file.

Use the basis_add_executable() function to add an executable target.

Link dependencies can be specified using the basis_target_link_libraries() function.

https://www.rad.upenn.edu/sbia/software/doxygen/basis/trunk/group__CMakeAPI.html%23gab7b7600c0ab4197db811f810a04670be



https://www.rad.upenn.edu/sbia/software/doxygen/basis/trunk/group__CMakeAPI.html%23gab2594b3327126ac531ef4ed806501406



27

Location of Executables

10/21/2011

The built main executable files can be found in the bin/ subdirectory of the build tree, while the built auxiliary executable files are in the lib/ subdirectory.

On Unix, the main executable files are installed into the directory <prefix>/bin/<project>/ and auxiliary executable files in <prefix>/lib/<project>/. Additionally, symbolic links are created for main executable files in <prefix>/bin/ if INSTALL_LINKS is set to ON and their SYMLINK_NAME property is not set to NONE.

On Windows, all executable files are installed in <prefix>/bin/<project>/.


28

Add an Executable

10/21/2011

Copy the helloc++.cxx file from the example/hellobasis/ directory of the BASIS installation to the src/ subdirectory of your project:

cd ~/local/src/hellobasis cp ${HELLOBASIS_RSC_DIR}/helloc++.cxx src/

Edit the src/CMakeLists.txt file and add the following line under the section “executable target(s)”:

basis_add_executable (helloc++.cxx)


29

Add an Executable

10/21/2011

Alternatively, you can use the implementations of this“Hello World!” program in Python, Perl, BASH or MATLAB, respectively, by using the source file hellopython.py, helloperl.pl, hellobash.sh, or hellomatlab.m, instead of helloc++.cxx.

In case of MATLAB, you also need to add a dependency on MATLAB before you can build executables from .m files as shown on the next slides. Moreover, you need to have a license for the MATLAB Compiler (mcc).


30

Add an Executable

10/21/2011

Add MATLAB as dependency: basisproject --root ~/local/src/hellobasis

--use MATLAB

Copy the hellomatlab.m file from the example/hellobasis/ directory of the BASIS installation to your src/ subdirectory:

cd ~/local/src/hellobasis cp ${HELLOBASIS_RSC_DIR}/hellomatlab.m src/

Edit the src/CMakeLists.txt file and add the following lines under the section “executable target(s)”:

basis_add_executable (hellomatlab.m)


31

Change Output Name

10/21/2011

The basis_add_executable() command uses the build target name as name for the built executable by default. Hence, as we provided only a single source file, the name of this source file without extension.

You can either specify a build target name corresponding to the desired executable file name as first argument to this function, or modify the output name explicitly by setting the OUTPUT_NAME property of the build target.


32

Change Output Name

10/21/2011

Add the following lines to the src/CMakeLists.txtfile after the basis_add_executable() statement:

basis_set_target_properties ( helloc++ PROPERTIES OUTPUT_NAME "hellobasis" )

Note: If you used one of the other source files, you need to change the first argument accordingly to hellopython, helloperl, hellobash, or hellomatlab, respectively.


33

Symbolic Links

10/21/2011

On Unix, BASIS creates upon installation by default symbolic links in the directory <prefix>/bin/ to the main executable files in <prefix>/bin/<project>/.

The reasons for this are as follows: By using the project name as name for a subdirectory in

bin/, lib/, share/,… we avoid name conflicts with other software packages.

By default, however, executables would be installed in /usr/local/bin/<project>/ which is not a standard path.

To make the use of the software more convenient and avoid another directory in the search path (PATH), we create the symbolic links.


34

Symbolic Links

10/21/2011

When the software is installed in /usr/local/,the environment variables need not to be modified.

The symbolic links are only created if there is no other file of the same name in the <prefix>/bin/ directory, thus, avoiding the overwrite of other executable files. The executable files of your software will still be installed in <prefix>/bin/<project>/.

The name of the symbolic links may differ from the name of the executable name. For example, to include a unique prefix such as the project name. See next slide for an example.


35

Symbolic Links

10/21/2011

Note that for the HelloBasis example of this tutorial, we chose an executable name which is identical to the project name (case-insensitive).

As we cannot have a subdirectory and a symbolic link with the same name in one directory, we need to either choose a different name for our executable, change the name of the symbolic link, or ask BASIS not to create a symbolic link.

For demonstration, on the next slide you will change the name of the symbolic link as described.


36

Symbolic Links

10/21/2011

In order to change the name of the symbolic link for the hellobasis executable, add CMake code such as the following to the src/CMakeLists.txt file after the basis_add_executable() statement: basis_set_target_properties ( helloc++ PROPERTIES SYMLINK_NAME "helloworld" )

Alternatively, just add the line SYMLINK_NAME "helloworld" after the previously added line OUTPUT_NAME "hellobasis"


37

Symbolic Links

10/21/2011

In order to add a prefix to the name of a symbolic link of an executable, you would add CMake code such as the following to the src/CMakeLists.txt file after the basis_add_executable() statement:

basis_set_target_properties ( helloc++ PROPERTIES SYMLINK_PREFIX "${PROJECT_NAME_LOWER}-" )

Do NOT do this for the HelloBasis example, we changed the name of the symbolic link already!


38

Symbolic Links

10/21/2011

The name of the symbolic link is composed of the values of the properties SYMLINK_PREFIX, SYMLINK_NAME, and SYMLINK_SUFFIX.

If you want to disable the creation of a symbolic link for a particular executable, set the property SYMLINK_NAME to NONE instead.


39

src/CMakeLists.txt

10/21/2011

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" )


40

Build the Executable

10/21/2011

After you added the executable target of your choice and edited the src/CMakeLists.txt file, build the project again to see if the executable is built successfully.

Therefore, run the commands: cd ~/local/src/hellobasis-build make

As we edited a CMakeLists.txt file, this will trigger a reconfiguration of the build system, i.e., the execution of CMake, before the actual build.


41

Run the Executable

10/21/2011

After the hellobasis executable got built, test it in the build tree by executing the command:

cd ~/local/src/hellobasis-build/bin ./hellobasis How is it going?


42

Install the Executable

10/21/2011

To install the executable, run: cd ~/local/src/hellobasis-build make install

Have a look at the content of ~/local/bin. You notice a subdirectory named hellobasis/ as well as a symbolic link named helloworld which links to the hellobasis executable file in the bin/hellobasis/ subdirectory.

Now test the installed executable. Remember, the directory ~/local/bin where we installed the symbolic link helloworld is already in your PATH. helloworld How is it going?


43

Adding LibrariesHow do I add libraries/modules to my project?

10/21/2011


44

Libraries

10/21/2011

Libraries are either static or shared libraries built from C++ sources or modules written in a scripting language such as Python, Perl, or BASH.

Additionally, MEX-files built from C++ sources are a special form of shared libraries as well as shared libraries build from MATLAB sources using the MATLAB Compiler.

In case of C++, we distinguish between public header files which are part of the public interface of your project and private header files which are only for use by your project.


45

How to Add Libraries

10/21/2011

Copy the source files of your library to the src/ subdirectory of your project. You can create further subdirectories within this directory if it helps to better organize your source files.

Copy the public header files to the directory include/sbia/<project>/, where <project> is the name of your project in lowercase only.

Edit the src/CMakeLists.txt file to add a library build target which will build the library file.

Use the basis_add_library() function to add a library target.

Link dependencies can be specified using the basis_target_link_libraries () function.

https://www.rad.upenn.edu/sbia/software/doxygen/basis/trunk/group__CMakeAPI.html%23ga3a56e2ed99608316be7309fcc090cc66

https://www.rad.upenn.edu/sbia/software/doxygen/basis/trunk/group__CMakeAPI.html%23ga3a56e2ed99608316be7309fcc090cc66





46

How to Add Libraries

10/21/2011

Note that external MEX-files or MEX-file targets of your project may be used as link dependency of an executable target build from MATLAB source files.

Use also basis_target_link_libraries() therefore.




47

Location of Libraries

10/21/2011

The built library files can be found in the lib/ subdirectory of the build tree, whereas Python modules are located in lib/python/sbia/<project>/ and Perl modules in lib/perl5/SBIA/<Project>/.

On Unix, the library files are installed into the directory <prefix>/lib/<project>.

On Windows, the .lib import library is installed in <prefix>/lib/<project>/ while the .dll runtime library is installed in <prefix>/bin/<project>/.


48

Add Private Library

10/21/2011

Copy the foo.cxx and foo.h files from the example/hellobasis/ directory of the BASIS installation to the src/ subdirectory of your project:

cd ~/local/src/hellobasis cp ${HELLOBASIS_RSC_DIR}/foo.* src/

Edit the src/CMakeLists.txt file and add the following line under the section “library target(s)”:

basis_add_library(foo.cxx)


49

Add Private Library

10/21/2011

Note that we did not specify the .h file here. CMake will analyze the .cxx file and add a dependency for us.

Note further that if your library would be build from more than one .cxx file, you need to specify a name for the build target as first argument to basis_add_library().


50

Add Public Library

10/21/2011

Before you can add a library target with public header files, you need to add the include/ subdirectory.

You can do so either manually or using the project tool: basisproject --root ~/local/src/hellobasis

--include

All public header files have to be put into this subdirectory. In order to have a unique file path for these header files which avoids name conflicts between projects, we use the subdirectory structure include/sbia/<project>/, which is automatically created by the project tool.


51

Add Public Library

10/21/2011

Now copy the bar.cxx file from the example/hellobasis/ directory of the BASIS installation to the src/ subdirectory of your project and the bar.h file into the include/ tree:

cd ~/local/src/hellobasis cp ${HELLOBASIS_RSC_DIR}/bar.cxx src/ cp ${HELLOBASIS_RSC_DIR}/bar.h

include/sbia/hellobasis/

Edit the src/CMakeLists.txt file and add the following line under the section “library target(s)”:

basis_add_library (bar.cxx)


52

Add Script Module

10/21/2011

To see how script modules are added, copy all or either one of the files foobar.py, FooBar.pm.in, and foobar.sh.in to the src/ subdirectory:

cd ~/local/src/hellobasis cp ${HELLOBASIS_RSC_DIR}/FooBar.pm.in src/

Edit the src/CMakeLists.txt file and add the following line under the section “library target(s)” for each of the copied module files:

basis_add_library (FooBar.pm)


53

The .in Suffix

10/21/2011

Note that some of these files have a .in file name suffix.

This suffix can be omitted in the basis_add_library() statement. The .in suffix indicates that the file is not usable as is, but contains patterns such as @PROJECT_NAME@ which are then replaced by BASIS during the build of the script file.

The substitution of these @*@ patterns is what we refer to as “building” script files.

The details on how such patterns are replaced and how it can be configured by what they are substituted will be discussed in a separate tutorial.


54

Build the Libraries

10/21/2011

After you added the library targets of your choice, build the project again to see if these libraries are built successfully.

Therefore, run the commands: cd ~/local/src/hellobasis-build make

As we edited a CMakeLists.txt file, this will trigger a reconfiguration of the build system, i.e., the execution of CMake, before the actual build.


55

Install the Libraries

10/21/2011

To see where the libraries and corresponding header files are installed, run the command:

cd ~/local/src/hellobasis-build make install

BASIS Tutorial by Andreas Schuh Copyright ©2011 University of Pennsylvania. Copyright ©2013...

Documents

Transcript of BASIS Tutorial by Andreas Schuh Copyright ©2011 University of Pennsylvania. Copyright ©2013...