HPX Resource Guide - STEllAR-GROUP/hpx GitHub Wiki

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 that is supported by an active development community. Our group relies heavily on three forms of communication: Discord Server, mailing lists, and tools provided through GitHub.

The fastest and most commonly used method to gain assistance with HPX is to join the Discord Server. The group maintains an almost constant presence on the channel (In part due to the global makeup of our collaborators), where you can reach us for questions and discussion about the library. Also, many of our tools are integrated with the channel and can be used from the platform.

To send out announcements, discuss more complex problems, and field general questions, we have set up several mailing lists 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]), focuses on technical discussions about issues, changes, and decisions 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 to allow 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 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 to 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. All users can then comment on these changes. 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 Summit, Piz Daint, Cori, Edison, Stampede, SuperMIC, and several other Top500 machines. Currently, however, most of our development work is done on a local development cluster called Rostam. Rostam is a heterogeneous machine with several generations, architectures, and manufacturers all used in the same cluster. You can read more about the machine on the Wiki page Running HPX on Rostam.

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 hosts the HPX repository and is where all changes made to the repository are made, reviewed, and accepted. GitHub provides a ticketing system for issues and a Wiki. To understand the group's procedures, 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 testbed for software development. With every commit to the HPX master branch, Buildbot will launch a series of tests on different platform configurations. Tests results are posted to a web interface that quickly points out errors that have been introduced into the codebase. As mentioned above, this tool has been integrated with the IRC channel. Whenever builds start and finish, the Buildbot will post an announcement of the build and the result of the tests. Additionally, users can trigger builds of branches off 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. This software package checks for guideline violations such as no license, excessive line length, and trailing whitespaces. Docker is a virtual image loader that allows users to create a container with an application and 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 the HPX Master branch, we also create and upload a new docker image to the HPX page on DockerHub.

Documentation

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

You can build the HPX documentation yourself or access the same documents online. 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. Several different documents are maintained in the Wiki, including instructions on contributing to the project, running HPX on specific machines, and other resources useful to the project.

Another resource that users can generate is the Doxygen code documentation. The Doxygen documentation allows users to search the HPX codebase more easily and provide information such as the file names and line numbers where header objects are instantiated. You can read more about generating Doxygen documentation on their website.

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 worldwide.

• http://stellar.cct.lsu.edu/ - This website is LSU-specific and contains most of the same information about HPX in addition to content that is more locally applicable.