HepForge > Documentation

HepForge user guide

This is the guide to the services provided by HepForge. Please check here and in the FAQ if you have a problem with the system. If you can't find an answer there, email us at admin@hepforge.org.

Shell account and filespace

Your HepForge account gives you full Unix shell access to our server, with user privileges: login by SSH'ing to username@login.hepforge.org. You have personal webspace, if you want to use it, at http://users.hepforge.org/~username which can be accessed by creating a personal public_html directory containing HTML files: mkdir ~/public_html; touch ~/public_html/index.html should do the trick. These pages will be visible on the Web at http://users.hepforge.org/~username/.

Project information

Each project has a home directory located at /hepforge/home/projname: the files in this directory should be group writeable. This contains a directory called project-config, in which various configuration files for the project are contained. You can edit these files, but be careful!

Aside from the configuration files for the Trac bug tracker and wiki system, your ~projname/project-config area contains the htpasswd and htgroup files for password-protecting areas of your Web space (see the Apache documentation for more information) and a project.xml file.

project.xml

The ~projname/project.xml file is used to define various features of your project. At the moment it is mainly used to define a "display name" and a short description for your project: these are used when generating the default title for HepForge web pages and in the project and download lists. In future, the "keywords" and "categories" elements in the XML file will be used for project categorisation and searching: we'll let you know how that works when we've decided!

Web space

You have project web space in /hepforge/home/projname/public_html. This can be viewed by pointing your Web browser to http://projects.hepforge.org/projname/. For the most part, the HepForge project web space is just like any normal web space, but there are a few special features:

A small HepForge "branding bar" is added to the top of each page;
Each page has some simple styling information associated with it. You can over-ride this if you want;
Basic HTML tags will be added to the top and bottom of each page if they aren't already there;
You can use PHP and CGI scripts to generate page content;
There is a simple mechanism for including a static header and footer on each page.

To expand on this last point, if you create a directory in your web area called "include" and place files in it called "header" and "footer", these files will be statically added to the top and bottom of every page respectively. This is a convenient way to add the HTML <head> section and a navigation menu to your site without having to write it on every page.

One unexpected feature of the HepForge web space is that Web sites written using "frames" will not display properly. This is due to the way that the HepForge Web server processes the pages you write, merging generic HepForge structures and definitions with the user-provided part of the page. In future we hope to make the degrading more "graceful". For now we'll justify the lack of functionality by pointing out that frames have plenty of useability issues of their own and that a lot of Web development guides (specifically, the ones that know what they're talking about) recommend not using them. When [XFrames][xframes] become more standard, we'll make an effort to support them.

As the number of HepForge accounts becomes larger, we will encounter security issues with all projects' web pages being served by the same web server user. We intend to solve this by making the web server execute as the appropriate user for the pages it is serving. However, this is rather far down our list of priorities and so we ask all users to be extremely careful if running any Web scripts not to store any sensitive information on the HepForge system and please, please, please don't make any directories world-writeable just so you can write to them using the web server. If you need to do any of the above, please ask us first and we'll work something out. The last thing any of us want is for the system to get compromised, which will result in lots of work for us and lots of inconvenience for everyone!

Version control systems

We encourage you to use a code management system. This will keep a record of all the changes you make to your code and allows roll-backs to previous known-good versions should something go wrong. Code management systems also allow several different developers to work on the same code at the same time, while minimising conflicts and change-merging difficulties. Lastly, you can "tag" particular states of your code so that they are easily retrieved, for example when you make a new release.

HepForge now only provides official support for the Subversion version control system, having dropped official support for CVS in early 2007. You can still use CVS, but there is no anonymous access anymore - we encourage CVS enthusiasts to think about moving to Subversion, which has an almost identical interface and behaviour. If you insist on CVS for your project, then the CERN Savannah system may offer you a better CVS service.

Subversion is a modern re-write of CVS which eliminates its fundamental flaws (for example: directory versioning, support for file moving and copying, support for symbolic links, commit atomicity etc.). Like CVS, SVN is based on a model of a central code repository from which developers "check out" code and into which they "commit" changes. We're happy to help with version control issues, particularly if it'll help introduce new developers to this essential feature of robust development! However, before contacting us with queries, you should read the online Subversion book. I find the answers to most questions in there, and chances are that any question you ask will be answered by looking there, too!

Your HepForge Subversion repository

Your project automatically has an SVN repository on HepForge, stored on the filesystem at /hepforge/svn/projname. If you want to restrict access to areas of this repository to particular authenticated users, you can use the svnserve.conf file, which is located in the conf directory of the repository (and is also symlinked from your project's project-config directory).

Users wanting to access your repository can use either the svn+ssh protocol or http. Commits are currently only possible over svn+ssh, which also requires a user account on HepForge so this is the advised protocol for project developers. HTTP is currently mainly useful for anonymous checkouts. The SVN path for svn+ssh developer access is svn+ssh://svn.hepforge.org/hepforge/svn/projname/.... SVN has a tendancy to want to make two or three SSH connections, so you may get quite a few password prompts: setting up public key based SSH access is advised if you'll be doing a lot of svn+ssh access.

For HTTP access you can view your repository via the Web by pointing your web browser at http://svn.hepforge.org/projname/.... The same path can be used as an argument to the svn command line program.

Finally, you can view your SVN repository by using the neat viewer built into your project's Trac system - more about that later.

You can also use these URLs with SSL encryption if you wish: to do so, replace the http with https in the URLs above.

Mailing lists

We're busy moving our lists system to a Mailman-based system which we actually have full control over. So the details below will soon be defunct. Watch this space...

By default, when we create a project, we will also set up two mailing lists, with names projname@cedar.ac.uk and projname-announce@cedar.ac.uk. The projname@cedar.ac.uk list is the contact list for project administrators and the projname-announce@cedar.ac.uk list is for you to keep users of your project informed of new versions or other useful developments. If required, we can also set up additional lists with suffixes other than "announce", but all lists for a given project will be prefixed with the project name.

You can manage your own mailing lists using the Majordomo system: this will allow you to specify, for example, whether the list is open or moderated (the admin contact list should be open, the announce list should be moderated, and if for example you set up a discussion list, that should be open too). A quick guide to Majordomo list management will be sent to the project admins when the list is set up — if you have any other queries, please contact us at hepforge@cedar.ac.uk.

Please note that you shouldn't send large attachments to the HepForge lists: the lists have message size quotas, which are easily overflowed by binary attachments.

Download manager

When you release a new version of your code, the "HepForge way" is to place it in the /downloads directory of your project home area, with a filename of the form name-x.y.z.tar.gz (other archive formats, e.g. .zip, can also be used). The name part can include any characters other than a minus (dash) character followed by a digit: this is used to indicate the division between name and version code. The version code can contain as many "levels" as you wish, though the threefold x, y, z form above is the most popular. The x, y, z variables can each have more than one digit and will be sorted appropriately: for example, "proj-2.0.1.tar.gz" is a less recent version of the "my-proj" code than "my-proj-10.0.1.tar.gz".

The archived code will be made available through a Web listing at http://www.hepforge.org/downloads and archive files can be linked to directly at http://www.hepforge.org/archive/projname/archive-filename.

FAQ manager

We are writing a Frequently Asked Questions system which builds FAQ web pages from an XML file defining question-answer pairs. It'll be available in the next HepForge upgrade — please ask if you're interested.

Bug tracker

All HepForge projects have access to a copy of the Trac bug tracking system, located at https://projects.hepforge.org/projname/trac/. Trac includes tracking of "tickets" (i.e. bug reports), as well as management of project milestones, integration with Subversion version control for your project's source code and a wiki, as described briefly in the next section.

Trac integrates very nicely with the rest of the HepForge system: users are authenticated using the standard Apache htpasswd and htgroup files system and HTTP authentication. These authentication files are stored in your project configuration area (/hepforge/home/projname/project-config) as described in the corresponding FAQ entry. Project configuration is performed using an interactive system from the command shell, called trac-admin, which is started as follows:

trac-admin /hepforge/projconf/projname/trac

You may also find it useful to configure Trac's appearance and behaviour using the trac.ini file located in .../project-config/trac/conf/. Using trac-admin and configuring Trac's ini file are described in great (and clear) detail in the Trac project wiki.

Note that SSL encryption is available for all HepForge pages and we recommend that logged-in Trac sessions for adding or modifying tickets, milestones etc. be carried out using it. Without SSL encryption, your project area login password will be sent across the internet in plain text and could easily be "sniffed". To use SSL encryption, make sure that the start of the web address in your browser reads https rather than just http. Your browser will probably also show a lock icon somewhere to indicate the security level. You might be interested in using a Trac plugin to force SSL access - see Trac Hacks for some interesting plugins.

Wiki

The Trac bug tracking system also includes a wiki, which integrates fully with the bug tracking features. A wiki is a collaborative documentation system, which uses a simplified markup language to produce web pages. Setting up users with different permissions to add, edit, delete (and so on) wiki pages, is also performed using the trac-admin script, so you should check out the Trac project wiki for wiki questions, too. If you can't find what you're looking for, send an email to us at hepforge@cedar.ac.uk and we'll see if we can help.

Again, note that SSL encryption is available for all HepForge pages and we recommend that logged-in Trac wiki sessions use it. Without SSL encryption, your project login password will be sent across the internet in plain text and could easily be "sniffed". To use SSL encryption, make sure that the start of the web address in your browser reads https rather than just http. Your Web browser will probably also show a lock icon somewhere to indicate the security level.

Software build/configuration systems

Native-compiled languages

We encourage all projects writing FORTRAN, C or C++ code to use the GNU autotools build system. This system automates the building and maintaining of Makefiles, transparently handles system-specific incompatibilities, allows to test for the existence of other (required or optional) packages on the user's system and provides a very standard ("./configure; make; make install") routine for users to build and install your code. Your HepForge shell account has access to the latest versions of the autotools programs and we are happy to help you get started with using them.

Java

If you are writing any Java software, then the Maven 2 build system is recommended: this performs much the same role as the autotools and handles unit tests and classpaths brilliantly. If you're into doing everything yourself, then Ant is also a good system, but is more analogous to a portable version of Make than automake.

Misc

We'd also be interested to hear any opinions on the Python-based SCons build system, if anyone's using it. It looks a lot more clean and funky than the GNU autotools system, but doesn't have the same size of user base.

You might also be interested in using the pkgwrite system, to build DEB and RPM packages of your software.