DEVELOPER

=== Developing with Command-Line Compilation ===

To compile and test the repository version of the breseq source code, you must have a C/C++ compiler,
autotools, autoconf, m4, and several other GNU tools installed on your system. You can use conda
with the included dev-environment.yml file to install packages needed for building and running breseq.

$ conda env create -f dev-environment.yml --prefix=$PWD/env
$ conda activate $PWD/env

This environment installs its own C/C++ compiler.

NOTE: Be careful on MacOSX to create the environment using the correct architecture
      matching your system (osx-arm64 versus osx-64)! This command can be used to get it right.

$ CONDA_SUBDIR=osx-`arch` conda env create -f dev-environment.yml --prefix=$PWD/env

Building requires running the ./bootstrap script when you have a fresh version from the repository or
whenever the autoconf configuration files have changed, for example when a new source file has been 
added to the project.

$ ./bootstrap.sh
$ ./configure
$ make

=== Consistency Test Instructions ===

The output of the consistency tests varies depending on different versions of bowtie2 and R. You should
use the exact versions of these tools specified in the dev-environment.yml Conda environment.

Run all tests (using Snakemake wrapper)
$ make test

For working with single tests when updating them, these commands can be run from the main source directory.

Command for running one test:
$ tests/test.sh test <test-name>

Clean existing test output:
$ tests/test.sh clean <test-name>

Same for building the output for a test (or rebuilding = combined run and build output)

$ tests/test.sh test <test-name>
$ tests/test.sh rebuild <test-name>

=== Developing with XCode ===

Open the included project file: src/breseq.xcodeproj

This project is set up to use the shared libraries and command-line tools installed by the conda 
environment. So, first create that environment as described above. Be sure the architecture type 
matches what is specified in XCode, or you will get linking errors! 

You must also run ./bootstrap and ./configure at the command line to create headers before XCode
will be able to compile the code.

For debugging within XCode, you need to go to "Product > Scheme > Edit Scheme..." after 
setting breseq/gdtools as the target and set/add three things.

1. Make sure that the environmental variable Name: PATH is set to Value: $CONDA_BIN_PATH:$PATH 
   in the Arguments tab so that bowtie2 and other runtime dependencies ar found when running 
   within XCode.
   
2. Set the command line options in the Arguments tab. These are the same as the command you 
   would type in the shell, except they omit the initial "breseq".

   breseq -r reference.gbk reads.fastq
   becomes
   Arguments: -r reference.gbk reads.fastq

3. Set the working directory in the Options tab, so that breseq will correctly find your
   input files at any relative paths you specify.

The MacOSX binary for distribution is created outside of XCode, as described below.

===  Creating the Source Archive for Distribution ===

First, be sure to update the breseq version in configure.ac

Then, generate a source archive for a given release:
$ make distcheck

=== Maintaining the Documentation ===

The user documentation lives in docs/ as mkdocs-flavored Markdown, built with the
mkdocs-material theme. mkdocs, mkdocs-material, and mike are included in the
breseq-dev conda environment (dev-environment.yml).

To preview your changes locally while editing:

$ mkdocs serve

This starts a local server (usually http://127.0.0.1:8000) that live-reloads as you
edit files under docs/.

Always use Markdown image syntax (`![alt text](images/foo.png)`), not raw HTML
`<img src="images/foo.png">` tags, when adding images. mkdocs only rewrites relative
paths correctly for Markdown-syntax images; raw HTML `<img>` src paths are passed
through untouched and will 404 once built, since every page builds one directory
level below the site root. `mkdocs build --strict` will NOT catch this mistake (it
only validates paths reachable through Markdown-syntax links/images), so check
rendered images manually with `mkdocs serve` before publishing.

Both `make dist`/`make distcheck` and `./binarydist.sh` automatically build the
documentation with mkdocs and bundle the built site (not the raw Markdown source)
into the distribution (as distdir/docs or BINARYDIR/docs, respectively). If mkdocs is
not installed, these steps are skipped with a warning rather than failing the build.

Published versions of the documentation are built and deployed automatically to
https://breseq.barricklab.org/ whenever a new vX.Y.Z release tag is pushed (see
.github/workflows/docs.yml). No manual publishing step is required for a normal
release.

You can also publish or replace a specific version on demand: go to the repository's
Actions tab, select the "docs" workflow, click "Run workflow", and enter a version
label (e.g. v0.40.1, matching the git tag). This builds docs from whatever branch you run it against but
publishes them under the version label you typed, so you can publish current docs
under an already-released version number without cutting a new tag. Re-running with
the same version label overwrites/replaces that published version -- useful for
testing the pipeline or fixing a docs mistake.

===  Building MacOSX Binary for Distribution ===

A special script exists for building a portable MacOSX universal binary:
$ ./binarydist.sh

See the directions inside of this file on how to install universal versions of the 
libraries correctly for static linking on MacOSX.