Index: contrib/trunk/README =================================================================== --- contrib/trunk/README (revision 1173) +++ contrib/trunk/README (revision 1174) @@ -1,66 +1,68 @@ This is the README file for the fastjet-contrib project http://fastjet.hepforge.org/contrib/ which provides a library of 3rd-party add-ons to FastJet (http://fastjet.fr/) ====================================================================== Instructions for generic users ------------------------------ You should have downloaded a tarball for the contrib. Unpack it, enter the resulting directory and run ./configure [--fastjet-config=FILE] [--prefix=...] [...] make make check # optional make install Once you have installed, a contrib named XYZ will typically be accessible through a line #include "fastjet/contrib/XYZ.hh" with the corresponding library available through -lXYZ . Queries about the fastjet-contrib project as a whole should be sent to Queries about individual contribs should be sent to the people mentioned in the contrib/AUTHORS file ====================================================================== For users who want the latest version (and for developers) ---------------------------------------------------------- To get started, you will need an account on hepforge. If you don't have one yet, go to https://www.hepforge.org/register -to create it. +to create it. You will also need to set up your ssh key on hepforge +(go to https://phab.hepforge.org/settings/user/USERNAME/page/ssh/ +where USERNAME is replaced by your username). -Get an svn checkout of the top-level directory +Now you can get an svn checkout of the top-level directory svn co svn+ssh://vcs@phab.hepforge.org/source/fastjetsvn/contrib/trunk fjcontrib which contains the scripts and a current list of contribs and their versions. Within the fjcontrib directory, get the contribs themselves by running ./scripts/update-contribs.sh usually, the contribs are tagged (released) versions and there is one svn checkout for each contrib. Then proceed with configure, make, etc. To get updates at a later stage: ./scripts/update-contribs.sh # all contribs ./scripts/update-contribs.sh ContribName # just a specific contrib ./scripts/update-contribs.sh ContribName version # specific version of a contrib The command always updates the top level directory. If "version" is "trunk", then you get the development area for the Contrib -- do this only if you're a developer of that contrib. For further information on development, see the file DEVEL-GUIDELINES. Index: contrib/trunk/DEVEL-GUIDELINES =================================================================== --- contrib/trunk/DEVEL-GUIDELINES (revision 1173) +++ contrib/trunk/DEVEL-GUIDELINES (revision 1174) @@ -1,244 +1,251 @@ Guidelines for the FastJet Contrib area --------------------------------------- The FastJet contrib area is intended for developers of FastJet-related C++ tools, so as to provide easy access to their work in a common, publicly accessible location. If you wish to add code to the fastjet-contrib repository, please follow the guidelines indicated below, intended to give users a reasonably uniform experience and to facilitate versioning and quality control. For further information about making contributions, please contact fastjet@projects.hepforge.org ====================================================================== Basic developer usage ===================== - + + # to get started you will need a hepforge account. Go to + # + # https://www.hepforge.org/register + # + # to create it. + # + # Then you will need to set up access through an ssh key. Go to + # + # https://phab.hepforge.org/settings/user/USERNAME/page/ssh/ + # + # to upload it (replace USERNAME with your actual username). Click on + # "SSH Key Actions" and select "Upload Public Key". + # check out the overall contrib directory - svn checkout http://fastjet.hepforge.org/svn/contrib/trunk fjcontrib + svn checkout svn+ssh://vcs@phab.hepforge.org/source/fastjetsvn/contrib/trunk fjcontrib cd fjcontrib # get the existing contribs (optional, but useful) scripts/update-contribs.sh # start your new contrib, choosing your own "ContribName" (*) # Running this script produces a template for the new contrib # in the form of a new ContribName/ subdirectory of fjcontrib, # including a basic Makefile (further info below) scripts/new-contrib-from-template.sh ContribName # once you have something worth committing, write to the fastjet contrib # maintainers at to get write access to the - # fjcontrib svn. - # - # [ To help us set up your account, if the htpasswd command is available - # to you, then send us your encrypted password using the output of - # - # htpasswd -mn YOUR-CHOSEN-USERNAME - # ] - # + # fjcontrib svn. We will need your username. + # and then run scripts/register-new-contrib.sh ContribName # within your pre-existing ContribName/ directory you can now "svn # add" your files, commit them etc. # you should probably also run "svn propset svn:keywords Id *.cc *.hh" # so that their $Id$ tag automatically gets updated when you commit # when you're ready to make a versioned release, make sure that + # # - all required files (AUTHORS, COPYING, NEWS etc.) are up to date # - VERSION includes the version number for the release # - "make check" and "make install" both work # - everything is committed # # At this point the fjcontrib maintainers are usually happy to have a # quick look through your code and provide comments based on # experience with other contribs. # # Once you're ready to make a release, run scripts/release-contrib.sh ContribName # send a mail to fastjet@projects.hepforge.org with a request for # that version to be made public (*) Note that if you have previously "registered" your contrib (i.e. you have run "scripts/register-new-contrib.sh ContribName") you can get it in a fresh checkout of the overall fjcontrib directory by running scripts/update-contribs.sh ContribName trunk Please refrain from developing other people's contribs without first consulting them! Note: currently there is no mechanism for handling external dependencies (ROOT, gsl, etc.), nor for handling dependencies between different contribs. ====================================================================== Further details =============== Each contribution is the responsibility of its authors. The FastJet authors will not provide direct support. Each contribution must be in a directory of its own. The name of the directory will also by default be used for the library component. Each contribution should be made available under the terms of the GNU General Public License (v2 or later), or if the author wishes, under a more permissive license that is compatible with the GNU GPL. Each contribution should include the following files (automatically put in place when you run scripts/new-contrib-from-template.sh, see below): - COPYING: giving license information - AUTHORS: names of authors, including current email addresses - README: giving a basic explanation of the scope and usage of the contrib and indication of which work should be cited by users of your code. Please mention any external dependencies, e.g. ROOT, GSL, Boost, etc. - at least one example program (e.g. example.cc) using the contrib tool or plugin, together with a file containing the expected output (example.ref). - VERSION: a version number, e.g. 1.0.x, which would be updated to 2.0.x in the event of a major change. - NEWS: to indicate what has changed in each new version - ChangeLog: finer grained details of day-to-day changes ====================================================================== Build system ============ Each contribution should include a Makefile. A reasonable default is generated when you run scripts/new-contrib-from-template.sh A few variables appearing at the top of the Makefile may need to be modified: - NAME - SRCS - EXAMPLES - INSTALLED_HEADERS Additionally you will need to ensure that "make check" works. By default it does the following: - builds the "example" program, - runs it, reading ../data/single-event.dat from standard input - compares the output to the "example.ref" file (after stripping lines that started with "#") In most cases, to get "make check" to work, it is sufficient to replace the template's example.ref file with the correct output from your program. If you want to use a different input file, modify the relevant line in the Makefile. You may also write your own Makefile (or adapt one from scripts/internal/Template/Makefile ). In this case - It should prominently define a variable FASTJETCONFIG near the beginning of the file. By default FASTJETCONFIG should be set to fastjet-config, i.e. the contribution should build out of the box if fastjet-config is in the user's path. - It should include the following targets . all . check . install . examples . clean . distclean ====================================================================== Structure of the svn repository =============================== The repository at - http://fastjet.hepforge.org/svn/contrib/ (read-only) - https://fastjet.hepforge.org/svn/contrib/ (read-write) - svn+ssh://svn.hepforge.org/hepforge/svn/fastjet/contrib/ (read-write) + svn+ssh://vcs@phab.hepforge.org/source/fastjetsvn/contrib/ (read-write) + https://phab.hepforge.org/source/fastjetsvn/browse/contrib/ (browse) is organised as follows: # area for the overall fastjet-contrib scripts and information about # currently used version of individual contribs. Currently only # maintainers of the overall fjcontrib area have write acces # trunk/ # development version tags/ # official releases branches/ # branches # areas for individual contribs. Developers each have access # to all contribs by default (for simplicity) contribs/ContribName/trunk # development version contribs/ContribName/tags # official releases contribs/ContribName/branches # branches Within the main fastjet contrib directory, the file "contribs.svn" file indicates which contribs (and their version) are to be extracted by scripts/update-contribs.sh ====================================================================== Guidelines for reviewing contribs ================================= [This part of the guidelines is in the process of being drafted] - Does the contrib do something non-trivial? I.e. does it do something that cannot already be easily done with a few lines of FJ code? - Is the contrib well documented? All classes, constructors, member functions, etc., that are exposed to the user should have an instructive comment about what they do (or be so well named that a comment is redundant). - Does the example(s) demonstrate all the main features of the code? - Does the example indicate what command-line should be used to run it? - Does the contrib make sensible use of existing FastJet features and, where relevant, does its interface follow the pattern of standard FJ3 interfaces? (E.g. with FunctionOfPseudoJet, Selectors, etc.). Conforming with existing interfaces helps give users a uniform experience. - Are namings logical and similar to those in FastJet: e.g. if the contrib is simply a plugin, the class name should end in "Plugin" and the contrib name should probably be the same as the class name. - Are the tests carried out as part of make check reasonably exhaustive? Are the contents of the reference results file sufficient to have a reasonable chance of spotting future changes? (E.g. a single bool as the output has a 50% chance of coming out right even if the code is misbehaving). - If you run the example with valgrind, does it run free of errors and memory leaks? We've found that valgrind tests are often better carried out on linux machines than on macs. - Does "make fragile-shared" work? Some people rely on it. - Are the README, AUTHORS, NEWS and ChangeLog files sensible? Are line lengths suitable for web viewing (e.g. no more than 80 characters per line). - Are the $Id$ tags set correctly in the files? You can set them by doing the following in your directory svn propset svn:keywords Id *.cc *.hh Index: contrib/trunk/scripts/internal/release-fjcontrib.sh =================================================================== --- contrib/trunk/scripts/internal/release-fjcontrib.sh (revision 1173) +++ contrib/trunk/scripts/internal/release-fjcontrib.sh (revision 1174) @@ -1,247 +1,247 @@ #!/bin/bash # # make a full release of the current trunk # Then produce a tarball # include function and svn location definitions, etc. . `dirname $0`/common.sh #======================================================================== # svn sanity checks #======================================================================== # make sure that everything is committed echo echo "Checking for pending modifications or updates (this may take a few seconds...)" if [[ ! -z "`svn status --show-updates | grep -v "^?" | grep -v "^Status"`" ]]; then echo echo "WARNING: There are pending modifications or updates:" echo svn status --show-updates | grep -v '^\?' echo get_yesno_answer "Are you really sure you want to proceed?" && exit 1 echo else echo "All files are up to date relative to the svn" fi # make sure there is a VERSION and it does not already exist version=`head -n1 VERSION` if [[ ! -z $(svn ls $svn_read/tags | grep "^$version/") ]]; then echo "Version $version of fjcontrib already exists. Aborting" exit 1 fi echo echo "The contribs.svn file points to the following contrib versions" echo echo "----------------------------------------------------------------" grep -v '^#' contribs.svn echo "----------------------------------------------------------------" echo get_yesno_answer "Do you want to proceed with the release of fjcontrib-$version?" && exit 1 #======================================================================== # check that the tools in contribs.svn behave OK #======================================================================== # get a clean checkout to perform sanity checks svn co $svn_read/trunk fjcontrib-$version || { echo "Failed to do the svn checkout"; exit 1; } cd fjcontrib-$version echo "------------------------------------------------------------------------" echo "Getting the contribs" echo "------------------------------------------------------------------------" if ./scripts/update-contribs.sh --force; then echo "Success." echo else echo "Failed." echo cd .. exit 1 fi echo "------------------------------------------------------------------------" echo "Configuring" echo "------------------------------------------------------------------------" # we need to determine whether to use fastjet-config from the path or # use the one from the configure invocation in the trunk is_in_path="yes" which fastjet-config > /dev/null || is_in_path="no" trunk_version="" if [[ -e "../Makefile" ]]; then trunk_version=$(head -n3 ../Makefile | tail -n1 | grep "\--fastjet-config=" | sed 's/.*--fastjet-config=//;s/ .*$//') fi if [[ -z "$trunk_version" ]]; then if [[ "$is_in_path" == "no" ]]; then echo "fastjet-config is not in your path and cannot be obtained from the trunk configuration. Aborting." cd .. exit 1 else echo "Using fastjet-config from your path" configure_options="" fi else if [[ "$is_in_path" == "no" ]]; then echo "using fastjet-config from the trunk configuration" configure_options=" --fastjet-config=${trunk_version}" else echo "fastjet-config can be either taken from your path or from $trunk_version." configure_options="" get_yesno_answer "Do you want to use the one from your trunk?" || { configure_options=" --fastjet-config=${trunk_version}" } fi fi if ./configure $configure_options; then echo "Success." echo else echo "Failed." echo cd .. exit 1 fi echo "------------------------------------------------------------------------" echo "Running make check" echo "------------------------------------------------------------------------" if make -j4 check; then echo "Success." echo else echo "Failed." echo cd .. exit 1 fi echo "------------------------------------------------------------------------" echo "Running make fragile-shared" echo "------------------------------------------------------------------------" if make -j4 fragile-shared; then echo "Success." echo else echo "Failed." echo cd .. exit 1 fi cd .. rm -Rf fjcontrib-$version if [ -d fjcontrib-$version ]; then echo "fjcontrib-$version still present. Aborting" fi #======================================================================== # tag the release #======================================================================= echo get_yesno_answer "Confirm you want to tag the release and make a tarball?" && exit 1 echo echo "------------------------------------------------------------------------" echo "Making a tag of fjcontrib version $version" echo "------------------------------------------------------------------------" echo svn copy -m "tagging fjcontrib-$version" $svn_write/trunk $svn_write/tags/$version svn copy -m "tagging fjcontrib-$version" $svn_write/trunk $svn_write/tags/$version #======================================================================== # produce a tarball #======================================================================== echo "------------------------------------------------------------------------" echo "Checking out tags/$version of fjcontrib" echo "------------------------------------------------------------------------" # using svn_write, because the http access sometimes doesn't # immediately see the up to date svn repository(?!) echo svn co $svn_write/tags/$version fjcontrib-$version svn co $svn_write/tags/$version fjcontrib-$version || { echo "Failed to checkout the new released version tags/$version"; exit 1; } cd fjcontrib-$version echo echo "------------------------------------------------------------------------" echo "Getting the contribs" echo "------------------------------------------------------------------------" if ./scripts/update-contribs.sh --force; then echo "Success." echo else echo "Failed." echo cd .. exit 1 fi # # get rid of a few things for developers and "svn-users" only # mkdir tmp # for fn in check.sh install-sh; do # mv scripts/internal/${fn} ./tmp # done # rm -Rf scripts # mkdir scripts # mkdir scripts/internal # for fn in tmp/*; do # mv $fn scripts/internal/${fn#tmp/} # done # rm DEVEL-GUIDELINES cd .. echo "------------------------------------------------------------------------" echo "Producing fjcontrib-$version.tar.gz" echo "------------------------------------------------------------------------" tar --exclude=".svn" \ --exclude="fjcontrib-$version/contribs.svn" \ --exclude="fjcontrib-$version/scripts" \ --exclude="fjcontrib-$version/DEVEL-GUIDELINES" \ -czf fjcontrib-$version.tar.gz fjcontrib-$version rm -Rf fjcontrib-$version echo echo "Success." echo #======================================================================== # update things on HepForge #======================================================================== echo get_yesno_answer "Confirm you want to upload to hepforge?" && exit 1 echo echo "------------------------------------------------------------------------" echo "Uploading to HepForge" echo "------------------------------------------------------------------------" echo "Uploading fjcontrib-$version.tar.gz" -scp fjcontrib-$version.tar.gz login.hepforge.org:~fastjet/public_html/contrib/downloads/ +scp fjcontrib-$version.tar.gz login.hepforge.org:$fastjet_web_dir/contrib/downloads/ mkdir hepforge_tmp echo "Generating info for the webpage" echo -n "$version" > hepforge_tmp/fjcversion.php `dirname $0`/generate-html-contents.pl > hepforge_tmp/contents-$version.html reldate=`date +"%e %B %Y"` echo -n $reldate > hepforge_tmp/fjcreldate.php echo "Uploading info for the webpage" -scp hepforge_tmp/fjcversion.php hepforge_tmp/fjcreldate.php login.hepforge.org:~fastjet/public_html/contrib/ -scp hepforge_tmp/contents-$version.html login.hepforge.org:~fastjet/public_html/contrib/contents/$version.html +scp hepforge_tmp/fjcversion.php hepforge_tmp/fjcreldate.php login.hepforge.org:$fastjet_web_dir/contrib/ +scp hepforge_tmp/contents-$version.html login.hepforge.org:$fastjet_web_dir/contrib/contents/$version.html echo "Ensuring fastjet group write access for new files on hepforge" # the following is needed because group sticky bit is erroneously not set # on the fastjet downloads directory, so group does not get set to fastjet #ssh login.hepforge.org chgrp fastjet "~fastjet/downloads/fjcontrib-$version.tar.gz" # now give fastjet group write permission on these files -ssh login.hepforge.org chmod g+w "~fastjet/public_html/contrib/fjcversion.php" "~fastjet/public_html/contrib/fjcreldate.php" "~fastjet/public_html/contrib/contents/$version.html" "~fastjet/public_html/contrib/downloads/fjcontrib-$version.tar.gz" +ssh login.hepforge.org chmod g+w "$fastjet_web_dir/contrib/fjcversion.php" "$fastjet_web_dir/contrib/fjcreldate.php" "$fastjet_web_dir/contrib/contents/$version.html" "$fastjet_web_dir/contrib/downloads/fjcontrib-$version.tar.gz" rm -Rf hepforge_tmp echo echo "Done" echo Index: contrib/trunk/scripts/internal/common.sh =================================================================== --- contrib/trunk/scripts/internal/common.sh (revision 1173) +++ contrib/trunk/scripts/internal/common.sh (revision 1174) @@ -1,114 +1,116 @@ # a list of definitions and tools that we'd like to ave an easy access # to # svn repositories for read and write access #svn_read=http://fastjet.hepforge.org/svn/contrib #svn_write=https://fastjet.hepforge.org/svn/contrib +fastjet_web_dir=~fastjet/public_html svn_read=svn+ssh://vcs@phab.hepforge.org/source/fastjetsvn/contrib svn_write=svn+ssh://vcs@phab.hepforge.org/source/fastjetsvn/contrib +fastjet_web_dir=/hepforge/projects/fastjet/public_html #svn_write=svn+ssh://svn.hepforge.org/hepforge/svn/fastjet/contrib # get the svn URL and fill # - mode : ro if http:// access; rw otherwise # - version : the version info # [None] is returned if the directory does not exist # [NoSVN] is returned if the directory is not under svn # # get_svn_info contrib mode version function get_svn_info(){ local __modevar=$2 local __versionvar=$3 # check if the directory exists if [[ ! -d $1 ]]; then eval $__modevar="[None]" eval $__versionvar="[None]" return 0 fi cd $1 # check if this is in svn svn info > /dev/null 2>&1 || { eval $__modevar="[NoSVN]" eval $__versionvar="[NoSVN]" cd .. return 0 } # get the full URL svn_url=$(svn info | grep "^URL:" | sed 's/^URL: //') eval $__versionvar="${svn_url#*/$1/}" if [[ "$svn_url" == "http:"* ]]; then eval $__modevar="ro" else eval $__modevar="rw" fi cd .. return 0 } # get an entry from a contrib file, filling the "version" variable # vwith the version number # # get_contrib_version contrib_name file version function get_contrib_version(){ local __resultvar=$3 # nasty hack: if the name of the "file" is "local_svn", # get the version number from the local svn checkout of the contribution if [[ "$2" == "local_svn" ]]; then get_svn_info $1 mode version eval $__resultvar="$version" return 0 fi # now deal with the version number as if it was an entry in "file" $2 if [[ -e $2 ]]; then # check if the file actually exists # entry=$(grep "^[ \t]*$1[ \t]" $2) # does not seem to work with tabs entry=$(grep "^[[:space:]]*$1[[:space:]]" $2) if [ -z "$entry" ]; then eval $__resultvar="[None]" else eval $__resultvar="`echo $entry | awk '{print $2}'`" fi else # file does not exist eval $__resultvar="[None]" fi } # get a yes/no answer # returns 0 for n/N/no # 1 for y/Y/yes function get_yesno_answer(){ while true; do echo -ne "$1 [y/n] " if [[ -z "$2" ]]; then read answer else answer="$2" # TODO: add a test that the answer is a valid one echo "$2" fi case $answer in y|Y|yes) return 1; break ;; n|N|no) return 0; break ;; esac done } # check if the local svn has pending modifications # check_pending_modifications contrib function check_pending_modifications(){ cd $1 result=$(svn status | grep -v "^?") if [[ ! -z "$result" ]]; then svn status | grep -v "^?" cd .. return 1 fi cd .. return 0 } Index: contrib/trunk/scripts/internal/generate-html-contents.pl =================================================================== --- contrib/trunk/scripts/internal/generate-html-contents.pl (revision 1173) +++ contrib/trunk/scripts/internal/generate-html-contents.pl (revision 1174) @@ -1,115 +1,120 @@ #!/usr/bin/perl -w # # Generate an html contents file for the current version of fjcontrib # # To be run from the main directory of a checkout of fjcontrib. # Best run from a directory that is a clean checkout of a tag. # # set to 1 to sort contribs alphabetically, 0 otherwise $sort=1; # set to 1 to include release date taken from svn tags, 0 otherwise. $include_date=1; $versions="contribs.svn"; #$svn="http://fastjet.hepforge.org/svn/contrib/contribs/"; +# links to read from the svn $svn_read="svn+ssh://vcs@phab.hepforge.org/source/fastjetsvn/contrib"; $svn=$svn_read."/contribs/"; +# link to browse the svn +$svnBrowse='https://phab.hepforge.org/source/fastjetsvn/browse/contrib/'; +# this ensures that one doesn't get the whole "blame" info, which is ugly +$svnPost='?as=source&blame=off'; $topversion=`head -1 VERSION`; chomp $topversion; # read in contribs.svn file, fill contribs hash open (VERSIONS, "<$versions") || die "Could not open $versions"; %contribs_hash=(); $contribs_array=(); while ($line = ) { if ($line =~ /^\s*([a-z][^\s]*)\s+([^\s]*)/i) { $contrib = $1; $version = $2; push @contribs_array, $contrib; $contribs_hash{$contrib} = $version; } } # sort contribs by alphabetical order if ($sort) { @contribs_array = sort keys %contribs_hash; } # write out html table $list=''; foreach ( @contribs_array ) { $contrib = $_; $version = $contribs_hash{$_}; if ($version =~ /^[0-9]/) {$version = "tags/$version";} ($textversion = $version) =~ s/tags\///; if($include_date) { # extract date of last version tag from svn $date = `svn info $svn$contrib/$version | grep "Last Changed Date" | awk '{print \$4}'`; # One could also use the --xml option and parse appropriately the output: # $date = `svn --xml list $svn$contrib/$version`; # At this stage, XML parsing is not implemented though. # #print $contrib." ".$date."\n"; } $list .= " - $contrib + $contrib $textversion "; if ($include_date) {$list .= "$date";} $list .= ""; if (-e "$contrib/README") { - $list .= 'README '; + $list .= 'README '; } if (-e "$contrib/NEWS") { - $list .= 'NEWS '; + $list .= 'NEWS '; } $list .= "\n"; } $head=' Version '.$topversion.' of FastJet Contrib is distributed with the following packages

'; if($include_date) {$head .= ' ';} $head .= ' '; $tail='
Package VersionRelease dateInformation
'; print $head, $list, $tail;