-
Notifications
You must be signed in to change notification settings - Fork 34
Developer HowTos
- Using Git
- Add a source file
- Add a new executable
- Getting started with Jenkins automated testing
- Compiling the b2 core documentation
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.
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.
-
Find the
Makemodule.am
file for the executable. It should be atcore/src/executablename/Makemodule.am
. -
Find the
programname_SOURCES
variable in theMakemodule.am
file. -
Add the full path, relative to
core/
, to the list. -
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 tomake
. -
Correct or amend these instructions if they were not complete.
Want to add a new compiled executable to be built when calling make
? Great, just follow these steps.
-
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 calledatomsmasher
, add the foldercore/src/atomsmasher
. -
Add the sources and headers to the appropriate folders.
-
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. -
Add contents to the
Makemodule.am
file. -
Write a comment for what the file is.
-
Add the program to the list of executables called
bin_PROGRAMS
using+=
; do not overwrite the variable holding the list of executables using+
. For examplebin_PROGRAMS+=atomsmasher
. -
List the sources, including headers, for the executable in the canonicalized variable
atomsmasher_SOURCES
. Use full pathnames. -
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. -
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)
. -
List the newly created
Makemodule.am
file in the mastercore/Makefile.am
. Add the lineinclude src/atomsmasher/Makemodule.am
to
core/Makefile.am
. Should go down with the otherinclude
statements. Order shouldn't matter. -
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.
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.
-
Choose a machine.
-
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.
-
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.
-
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. -
Get Jenkins. Install Jenkins.
-
Install plugins. For Jenkins, install the
xUnit test
plugin, andgit
plugin. -
Correct $PATH. Add required paths to the
PATH
variable in Jenkins. From Jenkins dashboard, goManage Jenkins ==> Configure System ==> Global Properties
, tick theEnvironment variables
box, andadd
a key-value pair, the key beingPATH
, 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. -
Add credentials. Also in
Jenkins ==> Configure Jenkins ==> Global Properties
, add some sort of credentials to the Git plugin space. -
Create new job. Return to the Jenkins dashboard. Create a
New Item
, and selectFreestyle Project
. Choose a name. Clickok
. Add a description -
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 ashttp://www.github.com/danbates/b2
. -
Specify the repo. In
Source Code Management
, selectGit
. Specify the path to the repo. May be the same as the URL above. -
Add some credentials. Click the
Add
button next to theCredentials
field, put in the info, then select what you just added from the drop down menu. -
Choose when to build. To have Jenkins check for repo commits every x minutes, in
Build Triggers
, tickPoll SCM
. Then add a schedule to theSchedule
field. For example, every 15 minutes, all year, would beH/15 * * * *
-
Set up the build process. In
Build
, clickAdd build step
. Choose whatever is appropriate for your project. For b2, it's probably aShell script
. In the newly created box, put in the steps. For example, you may chain commands together with&&
, such asautoreconf -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 -
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
. -
Add a post-build action. Choose
Publish xUnit test result report
. Add a parse by selecting the 'Add' dropdown, and selectBoostTest-1.x
. Then, list the names of the created reports from step 14. From the example above, it would beresults_classtest.xml
. -
Set how many failures are acceptable. 0 seems like a reasonable number for b2, as we are writing math software, not some game.
-
Finish editing job. Click the
Save
button. -
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, clickConsole Output
. Does it look correct? Did it build? Did it run the test? -
Edit your job as necessary to get it the way you like.
-
Revise this guide to reflect diversions you had to make to get going. The more details the better!
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.
-
Install Doxygen on your computer. (homebrew if you are on mac)
-
Install PlantUML on your computer. (homebrew if you are on mac)
-
Install GraphViz on your computer. (homebrew if you are on mac)
-
Define an environment variable,
PLANTUML_JAR_PATH
, as the path to the directory containingplantuml.jar
. Consider making this variable persistent if you will generate the documentation repeatedly across logins. -
Move to the
doc
folder, probably atb2/core/doc
. -
Run Doxygen, as
doxygen bertini.doxy.config
. -
Inspect the generated documentation, which should show up at
b2/core/doc/generated_documentation/doc.bertini/
. The root is named, of course,index.html
. -
Update this set of instructions if your setup process varied.