Skip to content

Developer HowTos

Jump to bottom Edit New page
daniel brake edited this page Nov 24, 2015 · 3 revisions

Contents

Using Git

Git is our version control system, with the main project hosted by the fictitious user bertiniteam at github.com/bertiniteam/b2.

Developers for Bertini2 are expected to become familiar with the branchy git version control tool. An excellent post describing a superior method for git use technique can be found here at nvie.com.

Add a source file

So you want to add a new source or header file to an executable which is built by Autotools in the core? Cool, here's how you do it.

  1. Find the Makemodule.am file for the executable. It should be at core/src/executablename/Makemodule.am.

  2. Find the programname_SOURCES variable in the Makemodule.am file.

  3. Add the full path, relative to core/, to the list.

  4. Test compile. make. It should re-run ./configure automatically, as you have changed included files. If not, then you may need to rerun ./configure with your options prior to make.

  5. Correct or amend these instructions if they were not complete.

contents

Add a new executable

Want to add a new compiled executable to be built when calling make? Great, just follow these steps.

  1. Add a new folder for the executable to core/src/. Give it the name of the executable. For example, if you want to add a new program called atomsmasher, add the folder core/src/atomsmasher .

  2. Add the sources and headers to the appropriate folders.

  3. Add a Makemodule.am file to the newly created directory; e.g. core/src/atomsmasher/Makemodule.am . It is just a plain text file with the .am extension, which is arbitrary.

  4. Add contents to the Makemodule.am file.

  5. Write a comment for what the file is.

  6. Add the program to the list of executables called bin_PROGRAMS using +=; do not overwrite the variable holding the list of executables using +. For example bin_PROGRAMS+=atomsmasher .

  7. List the sources, including headers, for the executable in the canonicalized variable atomsmasher_SOURCES . Use full pathnames.

  8. List the libraries it will link against, most particularly the Boost or MPI libraries, in the atomsmasher_LDADD variable. Libraries such as the math library (-lm) are found and added automatically to the list and do not need to be added. When configure searches for Boost and MPI, the libraries are not added to the global list of necessary libraries; instead, the programmer specifies that a particular library needs them.

  9. Add necessary flags for the compiler to atomsmasher_CXXFLAGS. This is NOT the place for things like -std=C++11, but rather programmatically determined things, such as $(BOOST_CPPFLAGS).

  10. List the newly created Makemodule.am file in the master core/Makefile.am. Add the line

    include src/atomsmasher/Makemodule.am

    to core/Makefile.am. Should go down with the other include statements. Order shouldn't matter.

  11. Edit these instructions to include any steps which varied for you.

Here's an example Makemodule.am file, for the bertini2 executable:

#this is src/bertini2/Makemodule.am  
# a comment describing the file

bin_PROGRAMS += bertini2 
# add the program to the list.  
# Must use += or you break the system

bertini2_SOURCES = src/bertini/bertini.cpp include/bertini.hpp 
# list the sources, whitespace separated.  
#Can continue on new lines by terminating previous line with \



bertini2_LDADD = $(BOOST_FILESYSTEM_LIB) $(BOOST_SYSTEM_LIB)  $(BOOST_CHRONO_LIB) $(BOOST_REGEX_LIB) \
    $(BOOST_TIMER_LIB) $(MPI_CXXLDFLAGS) $(BOOST_UNIT_TEST_FRAMEWORK_LIB) $(BOOST_SERIALIZATION_LIB)
# list the libraries which do not automatically get added to the list of libraries for all executables.  
# Boost and MPI are not automatically added.

bertini2_CXXFLAGS = $(BOOST_CPPFLAGS)
# add necessary compiler flags.  Probably only need Boost, but maybe another.  
# Not the place for things like -std=c++11

That should be about it. Enjoy.

contents

Getting started with Jenkins automated testing

The development pattern for B2 includes Unit Testing, frequent Git commits, automated building, and so on. We suggest you use Jenkins to help automate the code-commit-build-test-report pattern. To be set up to develop, you need some tools. This will guide you through the process. If during the process, you encounter difficulty or this guide is lacking, please modify this guide as you see fit.

  1. Choose a machine.

  2. Install Git. Ensure machine has Git installed, as well as Java, and any software dependencies. For B2, you need Boost (just install every Boost library). You should probably install MPICH, as well.

  3. Create a Git repository. This can take its form in many ways. Clone a repo from Github, Fork B2, create an empty directory and git init.

  4. Create some minimally functional code. Make the repository you created buildable, via some pattern. The author uses Autotools, so the build pattern is autoreconf -vfi && ./configure && make. Your pattern may vary. For B2 development, use Autotools. Ensure that you are able to manually build the software in the repo with minimal interaction with the user.

  5. Get Jenkins. Install Jenkins.

  6. Install plugins. For Jenkins, install the xUnit test plugin, and git plugin.

  7. Correct $PATH. Add required paths to the PATH variable in Jenkins. From Jenkins dashboard, go Manage Jenkins ==> Configure System ==> Global Properties, tick the Environment variables box, and add a key-value pair, the key being PATH, the value being /path/you/want:/other/path/you/want:$PATH. This is so you can access more than the trivial set of commands located in the /usr/bin or standard location.

  8. Add credentials. Also in Jenkins ==> Configure Jenkins ==> Global Properties, add some sort of credentials to the Git plugin space.

  9. Create new job. Return to the Jenkins dashboard. Create a New Item, and select Freestyle Project. Choose a name. Click ok. Add a description

  10. Specify the repo. In the GitHub project field, add the local path to the repo you are building and testing. For example, file:///Volumes/harddrivename/Users/username/folder1/folder2/reponame/ This can also be a genuine GitHub project URL, such as http://www.github.com/danbates/b2.

  11. Specify the repo. In Source Code Management, select Git. Specify the path to the repo. May be the same as the URL above.

  12. Add some credentials. Click the Add button next to the Credentials field, put in the info, then select what you just added from the drop down menu.

  13. Choose when to build. To have Jenkins check for repo commits every x minutes, in Build Triggers, tick Poll SCM. Then add a schedule to the Schedule field. For example, every 15 minutes, all year, would be H/15 * * * *

  14. Set up the build process. In Build, click Add build step. Choose whatever is appropriate for your project. For b2, it's probably a Shell script. In the newly created box, put in the steps. For example, you may chain commands together with &&, such as autoreconf -vfi && ./configure && make. Jenkins will report the build a failure if any of the commands you put in fail for any reason. In a few steps, we will test our build and inspect the console output

  15. Add a test command. As part of the build process, for a shell script, you can run the testing executable(s) just built. For example, b2_class_test. Ideally, this test program uses Boost.UnitTest, and is therefore capable of producing xml output. For such a Boost.UnitTest executable, add the options to the call --log_format=XML --log_sink=results_classtest.xml --log_level=test_suite --report_level=no.

  16. Add a post-build action. Choose Publish xUnit test result report. Add a parse by selecting the 'Add' dropdown, and select BoostTest-1.x. Then, list the names of the created reports from step 14. From the example above, it would be results_classtest.xml.

  17. Set how many failures are acceptable. 0 seems like a reasonable number for b2, as we are writing math software, not some game.

  18. Finish editing job. Click the Save button.

  19. Test your build. After saving, you should have returned to the main page for the job you are creating. Click Build now, to build. Inspect the results, by clicking on the name of the test (if this is your first one, it should be #1). On the left, click Console Output. Does it look correct? Did it build? Did it run the test?

  20. Edit your job as necessary to get it the way you like.

  21. Revise this guide to reflect diversions you had to make to get going. The more details the better!

contents

Compiling the b2 core documentation

The Bertini 2 documentation is assembled using Doxygen. All code (prototypes and classes) are expected to be commented using Doxygen, for the purpose of automatic documentation generation. In addition, flow charts and other UML documents are expected to be inline with these comments.

Here is a guide on how to prepare to build the documentation on your computer. You should only need to do this if you are a developer.

  1. Install Doxygen on your computer. (homebrew if you are on mac)

  2. Install PlantUML on your computer. (homebrew if you are on mac)

  3. Install GraphViz on your computer. (homebrew if you are on mac)

  4. Define an environment variable, PLANTUML_JAR_PATH, as the path to the directory containing plantuml.jar. Consider making this variable persistent if you will generate the documentation repeatedly across logins.

  5. Move to the doc folder, probably at b2/core/doc.

  6. Run Doxygen, as doxygen bertini.doxy.config.

  7. Inspect the generated documentation, which should show up at b2/core/doc/generated_documentation/doc.bertini/. The root is named, of course, index.html.

  8. Update this set of instructions if your setup process varied.

contents

Add a custom footer

Bertini2

Using the core

Compilation guide Cmake

Documentation

Developer resources

Contributors

Bertini 1 webpage

Clone this wiki locally