Merge pull request #302 from shintaro-iwasaki/pr/prep_release

update doxygen comments and README.md for the upcoming release

README.md

@@ -1,135 +1,129 @@
-  Argobots Release %VERSION%
+# Argobots
 
-Argobots is a lightweight, low-level threading and tasking framework. This
-release is an experimental version of Argobots that contains features related to
-user-level threads, tasklets, and some schedulers.
+Argobots is a lightweight, low-level threading and tasking framework.
 
-This README file should contain enough information to get you started with
-Argobots. More information about Argobots can be found at
-http://www.argobots.org.
+README.md should contain enough information to get you started with Argobots.
 
+1. [Getting Started](#1-getting-started)
+2. [Testing Argobots](#2-testing-argobots)
+3. [Reporting Problems](#3-reporting-problems)
+4. [Alternate Configure Options](#4-alternate-configure-options)
+5. [Compiler Flags](#5-compiler-flags)
+6. [Developer Builds](#6-developer-builds)
 
-1. Getting Started
-2. Testing Argobots
-3. Reporting Problems
-4. Alternate Configure Options
-5. Compiler Flags
-6. Developer Builds
-
+- More information about Argobots can be found at https://www.argobots.org
+- Complete Argobots API can be found at https://www.argobots.org/doxygen/latest/
 
 -------------------------------------------------------------------------------
 
-1. Getting Started
-==================
+## 1. Getting Started
 
 The following instructions take you through a sequence of steps to get the
-default configuration of Argobots up and running.
-
-(a) You will need the following prerequisites.
-
- - REQUIRED: This tar file argobots-%VERSION%.tar.gz
-
- - REQUIRED: A C compiler (gcc is sufficient)
-
- Also, you need to know what shell you are using since different shell has
- different command syntax. Command "echo $SHELL" prints out the current shell
- used by your terminal program.
-
-(b) Unpack the tar file and go to the top level directory:
+default configuration of Argobots up and running. For compilation, Argobots
+needs a C compiler (gcc is sufficient).
 
- tar xzf argobots-%VERSION%.tar.gz
- cd argobots-%VERSION%
+Also, you need to know what shell you are using since different shell has
+different command syntax. Command `echo $SHELL` prints out the current shell
+used by your terminal program.
 
- If your tar doesn't accept the z option, use
+### (a) Preparation
 
- gunzip argobots-%VERSION%.tar.gz
- tar xf argobots-%VERSION%.tar
- cd argobots-%VERSION%
+(a.1) *If you downloaded a release tarball of Argobots*, unpack the tar file and
+go to the top level directory:
 
-(c) Choose an installation directory, say /home/USERNAME/argobots-install,
-which is assumed to be non-existent or empty.
+```sh
+ tar xzf argobots.tar.gz
+ cd argobots
 
-(d) Configure Argobots specifying the installation directory:
+ ## If your `tar` doesn't accept the `z` option, use the following instead
+ # gunzip argobots.tar.gz
+ # tar xf argobots.tar
+ # cd argobots
+```
 
- for csh and tcsh:
+(a.2) *If you cloned Argobots from the GitHub page*, go to the top level
+directory and create `configure`:
 
-  ./configure --prefix=/home/USERNAME/argobots-install |& tee c.txt
+```sh
+ cd argobots
+ ./autogen.sh
+```
 
- for bash and sh:
+### (b) Choose an installation directory
 
-  ./configure --prefix=/home/USERNAME/argobots-install 2>&1 | tee c.txt
+The installation directory should be non-existent or empty.
+The following assumes `/home/USERNAME/argobots-install`
 
- Bourne-like shells, sh and bash, accept "2>&1 |". Csh-like shell, csh and
- tcsh, accept "|&". If a failure occurs, the configure command will display
- the error. Most errors are straight-forward to follow.
+### (c) Configure Argobots specifying the installation directory
 
-(e) Build Argobots:
+```sh
+ ./configure --prefix=/home/USERNAME/argobots-install 2>&1 | tee c.txt
 
- for csh and tcsh:
+ ## If you are using csh or tcsh:
+ # ./configure --prefix=/home/USERNAME/argobots-install |& tee c.txt
+```
 
-  make |& tee m.txt
+If a failure occurs, the configure command will display the error. Most errors
+are straight-forward to follow.
 
- for bash and sh:
+### (d) Build Argobots:
 
-  make 2>&1 | tee m.txt
+```sh
+ make 2>&1 | tee m.txt
 
- This step should succeed if there were no problems with the preceding step.
- Check file m.txt. If there were problems, do a "make clean" and then run
- make again with V=1.
+  ## If you are using csh or tcsh:
+  # make |& tee m.txt
+```
 
- make V=1 |& tee m.txt (for csh and tcsh)
+This step should succeed if there were no problems with the preceding step.
+Check file `m.txt`. If there were problems, do a `make clean` and then run
+make again with `V=1`.
 
- OR
+```sh
+ make V=1 2>&1 | tee m.txt
 
- make V=1 2>&1 | tee m.txt (for bash and sh)
+ ## If you are using csh or tcsh:
+ # make V=1 |& tee m.txt
+```
 
- Then go to step 3 below, for reporting the issue to the Argobots developers
-  and other users.
+If it does not work, go to step 3 below, for reporting the issue to the Argobots
+developers and other users.
 
-(f) Install Argobots:
+### (e) Install Argobots:
 
- for csh and tcsh:
+```sh
+ make install 2>&1 | tee mi.txt
 
-  make install |& tee mi.txt
+ ## If you are using csh or tcsh:
+ # make install |& tee mi.txt
+```
 
- for bash and sh:
+This step collects all required files in the `bin` subdirectory of the directory
+specified by the prefix argument to configure.
 
-  make install 2>&1 | tee mi.txt
 
- This step collects all required executables and scripts in the bin
- subdirectory of the directory specified by the prefix argument to configure.
-
--------------------------------------------------------------------------------
-
-2. Testing Argobots
-===================
+## 2. Testing Argobots
 
 To test Argobots, we package the Argobots test suite in the Argobots
-distribution. You can run the test suite in the test directory using:
+distribution. You can run the test suite in the `test` directory using:
 
-  make check
-
-  OR
-
-  make testing
+```sh
+ make check
+```
 
 The distribution also includes some Argobots examples. You can run them in the
-examples directory using:
-
-  make check
+`examples` directory using:
 
-  OR
-
-  make testing
+```sh
+ make check
+```
 
 If you run into any problems on running the test suite or examples, please
 follow step 3 below for reporting them to the Argobots developers and other
 users.
 
--------------------------------------------------------------------------------
 
-3. Reporting Problems
-=====================
+## 3. Reporting Problems
 
 If you have problems with the installation or usage of Argobots, please follow
 these steps:
@@ -151,12 +145,12 @@ Your email should contain the following files. ONCE AGAIN, PLEASE COMPRESS
 BEFORE SENDING, AS THE FILES CAN BE LARGE. Note that, depending on which step
 the build failed, some of the files might not exist.
 
- argobots-%VERSION%/c.txt (generated in step 1(d) above)
- argobots-%VERSION%/m.txt (generated in step 1(e) above)
- argobots-%VERSION%/mi.txt (generated in step 1(f) above)
- argobots-%VERSION%/config.log (generated in step 1(d) above)
-
- DID WE MENTION? DO NOT FORGET TO COMPRESS THESE FILES!
+```
+ argobots/c.txt  (generated in step 1(c) above)
+ argobots/m.txt  (generated in step 1(d) above)
+ argobots/mi.txt (generated in step 1(e) above)
+ argobots/config.log (generated in step 1(c) above)
+```
 
 Finally, please include the actual error you are seeing when running the
 application. If possible, please try to reproduce the error with a smaller
@@ -167,53 +161,49 @@ github issues page (https://github.com/pmodels/argobots/issues). Even if you
 believe you have found a bug, we recommend you sending an email to
 discuss@argobots.org first.
 
--------------------------------------------------------------------------------
 
-4. Alternate Configure Options
-==============================
+## 4. Alternate Configure Options
 
 Argobots has a number of other features. If you are exploring Argobots as part
 of a development project, you might want to tweak the Argobots build with the
 following configure options. A complete list of configuration options can be
 found using:
 
+```sh
  ./configure --help
+```
 
--------------------------------------------------------------------------------
 
-5. Compiler Flags
-=================
+## 5. Compiler Flags
 
 By default, Argobots automatically adds certain compiler optimizations to
 CFLAGS. The currently used optimization level is -O2.
 
 This optimization level can be changed with the --enable-fast option passed to
 configure. For example, to build Argobots with -O3, one can simply do:
 
+```sh
  ./configure --enable-fast=O3
+```
 
-Or to disable all compiler optimizations, one can do:
-
- ./configure --disable-fast
-
-For more details of --enable-fast, see the output of "./configure --help".
+For more details of `--enable-fast`, see the output of `./configure --help`.
 
 For performance testing, we recommend the following flags:
 
- ./configure --enable-fast=O3,ndebug --enable-tls-model=initial-exec \
-  --enable-affinity --disable-checks
+```sh
+ ./configure --enable-perf-opt --enable-affinity --disable-checks
+```
 
- OR
+For debugging, we recommend the following flags:
 
- ./configure --enable-perf-opt --enable-affinity --disable-checks
+```sh
+ ./configure --enable-fast=O0 --enable-debug=most
+```
 
--------------------------------------------------------------------------------
 
-6. Developer Builds
-===================
+## 6. Developer Builds
 
 For Argobots developers who want to directly work on the primary version control
 system, there are a few additional steps involved (people using the release
 tarballs do not have to follow these steps). Details about these steps can be
 found here: https://github.com/pmodels/argobots/wiki/Getting-and-Building
-

maint/release.pl

@@ -17,6 +17,7 @@
 my $root = cwd();
 my $with_autoconf = "";
 my $with_automake = "";
+my $enable_doxygen = 0;
 my $git_repo = "";
 
 my $logfile = "release.log";
@@ -32,6 +33,7 @@ sub usage
  print "\t--append-commit-id append git commit description (optional)\n";
  print "\t--with-autoconf autoconf directory (optional)\n";
  print "\t--with-automake automake directory (optional)\n";
+ print "\t--enable-doxygen enable doxygen (optional)\n";
 
  print "\n";
 
@@ -120,6 +122,7 @@ sub run_cmd
  "append-commit-id!" => \$append_commit_id,
  "with-autoconf=s" => \$with_autoconf,
  "with-automake=s" => \$with_automake,
+ "enable-doxygen!" => \$enable_doxygen,
  "help" => \&usage
 ) or die "unable to parse options, stopped";
 
@@ -135,6 +138,14 @@ sub run_cmd
 check_package("latex");
 check_package("autoconf");
 check_package("automake");
+if ($enable_doxygen) {
+ check_package("doxygen");
+ my $official_doxygen_ver = "1.8.17";
+ my $doxygen_ver = `doxygen --version | head -n 1 | grep "$official_doxygen_ver"`;
+ if ($doxygen_ver eq "") {
+ die "ERROR: Doxygen ${official_doxygen_ver} is not installed. Consider setting --enable-doxygen. Stopped";
+ }
+}
 print("\n");
 
 
@@ -189,6 +200,9 @@ sub run_cmd
 system(qq(perl -p -i -e 's/\\[ABT_RELEASE_DATE_m4\\],\\[unreleased development copy\\]/[ABT_RELEASE_DATE_m4],[$date]/g' ./maint/version.m4));
 print("done\n");
 
+# Add version information to README.md
+system(qq(perl -p -i -e 's/^# Argobots\n/# Argobots ${version}\n/g' README.md));
+
 # Create configure
 print("===> Creating configure in the main codebase... ");
 chdir($expdir);
@@ -210,17 +224,19 @@ sub run_cmd
 run_cmd("find . -name .tmp | xargs rm -rf");
 print("done\n");
 
-# TODO: Get docs
-#print("===> Creating secondary codebase for the docs... ");
-#run_cmd("mkdir ${expdir}-build");
-#chdir("${expdir}-build");
-#run_cmd("${expdir}/configure");
-#run_cmd("(make doxygen)");
-#print("done\n");
-#
-#print("===> Copying docs over... ");
-#run_cmd("cp -a doc/doxygen/html ${expdir}/");
-#print("done\n");
+if ($enable_doxygen) {
+ # Create doxygen files
+ print("===> Creating secondary codebase for the docs... ${expdir}-build ");
+ run_cmd("mkdir ${expdir}-build");
+ chdir("${expdir}-build");
+ run_cmd("${expdir}/configure");
+ run_cmd("(make doxygen)");
+ print("done\n");
+
+ print("===> Copying docs over... cp -a doc/doxygen/html ${expdir}/ ");
+ run_cmd("cp -a doc/doxygen ${expdir}/doc");
+ print("done\n");
+};
 
 # Create the main tarball
 print("===> Creating the final argobots tarball... ");