add BUILD.md

BUILD.md

@@ -0,0 +1,65 @@
+----------------
+
+# Instructions for building, checking, and installing
+
+## Makefile usage
+
+A `Makefile` is provided.  Most of the rules are defined in the `rules.mk` file.
+The following key variables are defined in the `Makefile`.
+
+- `REPODIR`: the name of the directory in which a local copy of the Git repo used for publishing source and documentation is located.
+- `INCLUDES`: names of header files that will be copied to `inst/includes`
+- `HEADERS`: names of header files that must be rebuilt whenever source code changes.
+
+The key targets are:
+
+- `roxy`: runs `devtools::document()` to build the help pages (in `man/`), the package `NAMESPACE`, and the collation order in `DESCRIPTION`.
+- `dist`: builds the package source tarball.
+- `install`: installs the package locally for testing.
+- `tests`: runs `make` in the `tests/` directory, causing tests to be updated as needed.
+- `clean`: cleans the directory of files created during builds and tests.
+- `fresh`: resets the directory for a fresh rebuild.
+
+- `htmlhelp`: builds the package manual in HTML and PDF formats.
+  This command also causes `doxygen` to be run, which produces HTML documentation of the C/C++ source code.
+  These documentation files are installed into the `REPODIR/manuals` directory.
+- `www`: installs the package and runs `make` in the `www` directory.
+  This causes vignettes to be updated, among other things.
+- `NEWS`: builds the plain-text package NEWS file.
+- `instdocs`: runs `make` in the `inst/docs` directory.
+
+- `check`: runs `devtools::check()`.
+- `qcheck`: like `check`, but tests in `tests/` are not run.
+- `qqcheck`: like `qcheck`, but checks for code-documentation mismatch and examples are not run.
+- `xcheck`: runs `devtools::check(cran=TRUE)`, i.e., the additional checks for CRAN suitability are also run.
+- `ycheck`: runs `xcheck` but tests and examples that are ordinarily not run (because expensive) are run.
+- `vcheck`: runs `check` and then tests for memory leaks using `valgrind`.
+  One must examine the output (printed to the console and also stored in a file, the name of which ends in `-Ex.Rout`.
+- `revdeps`: causes checks of reverse-dependent packages to run.
+  The outputs are stored under the `revdep` directory.
+
+- `session`: installs the package locally and then runs an **R** session for interactive testing.
+  This session is controlled by the `RSESSION` environment variable.
+  By default, this runs an `emacs -f R` session.
+- `rsession`: like `session`, but a naked **R** session is started: `RSESSION=R`.
+- `debug`: like `rsession`, but the **R** session is started under a debugger.
+  By default, the `gdb` debugger is used: `RSESSION=R -d gdb`.
+
+- `publish`: causes source and binary tarballs to be installed in the REPODIR respository.
+- `covr`: runs `covr::package_coverage()` to evaluate unit-test coverage.
+  Results are stored in `covr.rds`.
+- `vcovr`: like `covr`, but results are displayed in a browser. 
+
+----------------
+
+# Github Actions
+
+Several Github Actions are defined in `.github/workflows`:
+
+- `r-cmd-check`: runs checks on various platforms.
+- `test-coverage`: runs `covr::codecov` to upload unit-test coverage information to [codecov.io](https://codecov.io).
+- `binary-build`: causes binary tarballs to be built for OS X and Windows platforms.
+
+These must be updated manually from time to time as the Actions on which they depend change.
+
+----------------

CRAN.md

@@ -1,3 +1,5 @@
+-------------------------
+
 # Preparing a CRAN submission
 
 ## Checks
@@ -29,13 +31,13 @@ git push github v4.6
 - perform extra checks:
   - `make xcheck`
   - `make ycheck`
-  - `make vcheck`
-  - examine `pomp-Ex.Rout` for `valgrind` output
+  - `make vcheck` and examine `valgrind` output in `pomp-Ex.Rout` for evidence of memory leaks.
+  - `make revdeps`
 
 ## Submitting
 
 - Use the [webform](https://xmpalantir.wu.ac.at/cransubmit/) for submission.
-- **Submission note text:**  
+- **Example submission note text:**  
   The package has been checked under R-4.1.0, R-release, and R-devel on linux, osx, and windows.
   I have checked for memory leaks using 'valgrind'.
   There are two new NOTEs generated, concerning S3 generic/method consistency.
@@ -53,3 +55,5 @@ git push github v4.6
   - `make publish`
   - Then push changes to `kingaa.github.io`
 - Make `X.X.0.0` release for Github site.
+
+-------------------------

README.md

@@ -1,6 +1,6 @@
-## **pomp**
+# **pomp**
 
-### an *R* package for statistical inference on partially observed Markov processes
+## an *R* package for statistical inference on partially observed Markov processes
 
 [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 [![Development Release](https://img.shields.io/github/release/kingaa/pomp.svg)](https://github.com/kingaa/pomp/releases/latest)

TODO.md

@@ -1,3 +1,5 @@
+-------------
+
 # pomp to-do list
 
 ## For pomp:
@@ -82,3 +84,5 @@
 - more/better examples
 	- need examples of objective function methods
 	- `pmcmc` examples
+
+-------------