Skip to content

Home

Jump to bottom Edit New page
Victor Villas edited this page Feb 5, 2016 · 81 revisions

Boost.uBLAS R&D Wiki

This is the uBLAS Research and Development Wiki that is used for exchange of ideas, development management and task planning.

Guidelines:

Compiling and running the unit tests:

The following will download all boost libraries from github.com/boostorg and will setup a basic system for uBlas development using the github.com/uBLAS/ repository:

# 1. Setup git
# On OS X, Linux:
git config --global core.autocrlf input
# On Windows:
git config --global core.autocrlf true

# 2. Clone the modular-boost repository
git clone https://github.com/boostorg/boost modular-boost
cd modular-boost

# 3. Replace the default submodule with the ublas dev repository:
# Edit .gitmodules and change:
# url = ../ublas.git
# to
# url = https://github.com/uBLAS/ublas.git
# or in POSIX systems (or git bash/mingw in windows): 
sed -i 's/url = ..\/ublas.git/url = https:\/\/github.com\/uBLAS\/ublas.git/g' .gitmodules


# 4. Sync and clone all the submodules
git submodule sync
git submodule update --init --recursive 

# 5. Build boost.build
# On OS X, Linux:
./bootstrap.sh
# windows:
bootstrap.bat

# 6. put the b2 executable somewhere in your PATH

# 7. Run the uBlas tests:
cd libs/numeric/ublas/test
git checkout develop # Or any branch you are interested in
b2

From now on you can work in modular-boost/libs/numeric/ublas using regular git commands. For a list of basic git commands please look at: Basic GIT commands

Testing how a merge will behave:

Very often you will need to test a merge prior to actually merging. To do that you can simulate the merge by creating a local branch that is a copy of the target branch and merge into that. After you have checked that the merge works as expected you can delete the local branch.

# For example let's test a merge into develop

# First let's clone the target branch:
git checkout develop
git branch develop_merge_test
git checkout develop_merge_test
# Let's merge 
git merge feature_my_feature_branch

# Resolve any issues or run tests
# When you are done you can force delete the local test branch:
git checkout develop
git branch -d develop_merge_test
# or force delete:
git branch -D develop_merge_test

Fetching from upstream (boostorg/uBLAS):

Those instructions apply only to core uBlas developers and is a facility to fetch any modifications that might happen ( that shouldn't) on the boostorg/ublas repo.

# First create an upstream remote that points to boostorg/ublas:
git remote add ublas_upstream https://github.com/boostorg/ublas
#make sure you are in develop:
git checkout develop
# Fetch the repository from upstream (boostorg/ublas) to your local copy:
git fetch ublas_upstream
# Merge from upstream (boostorg/ublas) to your local copy of develop:
git merge ublas_upstream/develop
# if you want to merge another branch (i.e. master) simply do : 
# git checkout master; git merge ublas_upstream/master

Syncing with the rest of Boost

Sometimes you may need to pull the rest of boost in your local copy. In the case cd to the modular-boost folder and execute:

# Make sure that we let git overwrite the copy of .gitmodules
git checkout -- .gitmodules

# Pull the entirety of boost
git pull --recurse-submodules

# Put Ublas/ublas repo back in .gitmodules
sed -i 's/url = ..\/ublas.git/url = https:\/\/github.com\/uBLAS\/ublas.git/g' .gitmodules

#  Sync and clone all the submodules (in case new ones are added)
git submodule sync
git submodule update --init --recursive

uBLAS resources:

Documentation is available at these addresses:

Depending on your familiarity with uBLAS you may want to consult the effective uBLAS wiki and Gunter Winkler's examples:

http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Effective_UBLAS

http://www.guwi17.de/ublas/index.html

http://www.guwi17.de/ublas/examples/

General guidelines:

For a feature to be acceptable into the uBLAS source code it must:

  1. Have appropriate regression tests. A good example can be found at https://github.com/uBLAS/ublas/blob/ublas_develop/test/test_assignment.cpp. A test/test_xxx.cpp file is probably the start of any new feature development.
  2. Perform on par or better than the respective feature of a high performance library (Intel MKL, ACML, Eigen3, GotoBLAS)
  3. Come with benchmark code that demonstrates its performance.
  4. Come with simple tutorial/example code integrated into the documentation
  5. Have reasonable doxygen documentation

For a bugfix: Any of 1 to 5 that may apply.

Branches:

TODO: Rename branches using the following scheme: feature/ublas00001_xxxxxx bugfix/ublas00002_xxxx bugfix/ublas00003_xxxx ...

Add a custom footer
Add a custom sidebar
Clone this wiki locally