HPX Resource Guide

This document contains information about the resources available to the developers of HPX.

##Table of Contents

• Communications
• Machines
• Tools
• Documentation
• Websites

##Communications

HPX is a fast growing library which is supported by an active development community. Our group relies heavily on three forms of communication: IRC, mailing lists, and tools provided through GitHub.

The fastest and one of the most commonly used methods to gain assistance with HPX is to join the #ste||ar IRC channel on Freenode. The group maintains and almost constant presence on the channel (In part due to the global make up of our collaborators) where we can be reached for questions and discussion about the library. In addition, many of our tools are integrated with the channel and can be used from the platform. You can find the chat logs at http://irc.cct.lsu.edu/.

In order to send out announcements, discuss more complex problems, and field general questions we have setup several mailing list around HPX development. HPX-Users ([email protected]) is a mailing list set up to disseminate announcements, updates, breaking changes to the HPX user community. This list is most commonly used and most useful to new users. Our developer’s mailing list, HPX-Devel ([email protected]), is focused on technical discussions about issues, changes, and decisions that are internal to HPX. The list, however, is open to all of those interested in joining. Finally, our last mailing list is the HPX-Commits ([email protected]) list. This listserv provides an email for all commits to the HPX master branch.

You can sign up for these mailing lists here:

• HPX-Users Subscription
• HPX-Devel Subscription
• HPX-Commits Subscription

The HPX-Users and HPX-Devel list archives are also available on GMANE. This allows users to browse the archives with advanced search features not available with our listserv software. You can find the archives here:

• HPX-Users Archive
• HPX-Devel Archive

The final major form of communication in the group is the use of tickets and comments hosted on the GitHub site. When users find bugs in the code we ask that those bugs be reported using the issue tracker on GitHub. Creating, commenting, and tracking issues is easily accomplished on the site and is the main way that we resolve problems in HPX. When changes have been made to the code that a user wishes to merge into master, the user can submit a pull request. These changes can then be commented on by all users. In this way we can get community feedback, involvement, and error checking into our commit process. We will explain other features of GitHub in later sections.

##Machines

HPX experiments are set up to run on many machines including Babbage, Edison, SuperMIC, and other Top500 machines. Currently, however, most of our development work is done on a local development cluster called Hermione. Hermione is a heterogeneous machine with several generations, architectures, and manufactures all used in the same cluster. You can read more about the machine on the Wiki page [Running HPX on Hermione] (https://github.com/STEllAR-GROUP/hpx/wiki/Running-HPX-on-Hermione).

##Tools

HPX is developed with the help of several software tools including GitHub, Buildbot, CircleCI, and Docker.

GitHub is the most important tool of HPX development. GitHub provides the home of the HPX repository and is where all changes made to the repository are made, reviewed, and accepted. GitHub provides a ticketing system for [issues] (https://github.com/STEllAR-GROUP/hpx/issues) and a [Wiki] (https://github.com/STEllAR-GROUP/hpx/wiki) from which this document was retrieved. In order to understand the procedures that the group uses please read some of the other documents in the Wiki. They explain how the outline of the codebase, standards used to evaluate code quality, and procedures to integrate code into the repo.

The next most often used tool is Buildbot. This tool is a platform designed to support a distributed test bed for software development. With every commit to the HPX master branch Buildbot will launch a series of tests on different platform configurations. The results of these test are then posted in a [web interface] (http://hermione.cct.lsu.edu/) that quickly points our errors that have been introduced into the code base. As mentioned above, this tool has been integrated with the IRC channel. Whenever builds start and are finished, the Buildbot will post an announcement of the build and the result of the tests. In addition, users can trigger builds of branches off of the master branch by messaging the Buildbot on IRC. Address "help" or "commands" to the Buildbot for more information.

Each pull request submitted to HPX master goes through a sanity check before it is merged into master. This sanity check is run with a tool called CircleCI. Unlike Buildbot, CircleCI only compiles the library, builds relevant components, runs hello_world, and runs the inspect tool. This simple test suite helps us keep obvious errors out of the master branch. CircleCI works closely with two other tools: the inspect tool and Docker. The inspect tool is derived from the [Boost Inspect Tool] (http://www.boost.org/doc/libs/1_59_0/tools/inspect/). This software package checks for guideline violations such as no license, excessive line length, and trailing whitespaces. Docker is a virtual image loader which allows users to create a container with an application and all of its software dependencies. We use Docker to load a container with all of the prerequisites for building HPX. CircleCI then does all of its work inside of the container. Each time there is a successful build of HPX Master branch we also create a new docker image which is uploaded to the [HPX CircleCI site] (https://circleci.com/gh/STEllAR-GROUP/hpx/tree/master).

##Documentation

There are three main sources of HPX documentation the documentation in the code base, the HPX wiki, and the Doxygen documentation.

HPX has documentation which can be built from the code base. The same documents can be accessed [online] (http://stellar-group.org/libraries/hpx/docs/). With each release, we post the associated document online and nightly we generate a new document built from the current state of the documentation in the master branch.

The HPX community also heavily uses the [HPX Wiki] (https://github.com/STEllAR-GROUP/hpx/wiki). Several different documents are maintained in the Wiki including instructions on how to contribute to the project, information about running HPX on specific machines, and other resources useful to the project.

One other resource that can be generated is the Doxygen code documentation. Users can build Doxygen documentation in order to search the HPX codebase more easily. Doxygen will provide information such as the file names and line numbers where header objects are instantiated. You can read more about genetrating Doxygen documentation on their [website] (http://www.stack.nl/~dimitri/doxygen/).

##Websites

News, articles, and other information about HPX are posted on two websites that our group maintains.

• http://stellar-group.org/ - This site is the homepage for the STE||AR Group. On this site users can find information about HPX and other libraries developed by our collaborators around the world.

• http://stellar.cct.lsu.edu/ - Is an LSU specific site which contains most of the same information about HPX, however we also host content which is more locally applicable.