Update documentation in preparation for release 2.5.3

BOWTIE2_VERSION

@@ -1 +1 @@
-2.5.2
+2.5.3

MANUAL

@@ -171,6 +171,14 @@ Finally, building the build executable: * with OpenMP support --
 [g]make bowtie2-build-s USE_SAIS_OPENMP=1 * without OpenMP support --
 [g]make bowtie2-build-s USE_SAIS=1
 
+Building with CMake
+
+To build Bowtie2 with SRA and libsais support issue the following
+command: * cmake . -D USE_SRA=1 -D USE_SAIS=1 && cmake --build .
+
+CMake will take care of building and linking against the specified
+dependencies.
+
 Adding to PATH
 
 By adding your new Bowtie 2 directory to your PATH environment variable,

MANUAL.markdown

@@ -173,6 +173,13 @@ Finally, building the build executable:
 * with OpenMP support -- `[g]make bowtie2-build-s USE_SAIS_OPENMP=1`
 * without OpenMP support -- `[g]make bowtie2-build-s USE_SAIS=1`
 
+### Building with CMake ###
+
+To build Bowtie2 with SRA and libsais support issue the following command:
+* `cmake . -D USE_SRA=1 -D USE_SAIS=1 && cmake --build .`
+
+CMake will take care of building and linking against the specified dependencies.
+
 Adding to PATH
 --------------
 

NEWS

@@ -4,7 +4,7 @@ Bowtie 2 NEWS
 Bowtie 2 is available for download from the project website,
 http://bowtie-bio.sf.net/bowtie2 and on Github,
 https://github.com/BenLangmead/bowtie2/releases.  2.0.0-beta1 is
-the first version released to the public and 2.5.2 is the latest
+the first version released to the public and 2.5.3 is the latest
 version.  Bowtie 2 is licensed under the GPLv3 license.  See `LICENSE'
 file for details.
 
@@ -19,6 +19,15 @@ Please report any issues to the Bowtie 2 Github page or using the Sourceforge bu
 Version Release History
 =======================
 
+## Version 2.5.3 - Jan 11, 2024 ##
+
+   * Fixed an issue causing `bowtie2`'s memory usage to increase over time.
+   * Fixed an issue causing `bowtie2` to crash when processing empty FASTQ records.
+   * Fixed an issue that would cause `bowtie2` to erroneously treat `-f` and `-F` as mutually exclusive.
+   * Add optional support for `libsais` to `bowtie2-build` for faster index building.
+     N.B. -- small indexes are capped at 2GB when using `libsais` as opposed to 4GB when using the
+     default blockwise algorithm. See MANUAL for more details.
+
 ## Version 2.5.2 - Oct 13, 2023 ##
 
 ### bowtie2 ###

README.md

@@ -2,7 +2,7 @@
 <!-- badges: start -->
 ![Random Tests](https://github.com/BenLangmead/bowtie2/actions/workflows/random-tests.yml/badge.svg)
 ![Simple Tests](https://github.com/BenLangmead/bowtie2/actions/workflows/simple-tests.yml/badge.svg)
-[![Version](https://img.shields.io/badge/version-2.5.2-green.svg)](https://shields.io/)
+[![Version](https://img.shields.io/badge/version-2.5.3-green.svg)](https://shields.io/)
 <!-- [![Build Status](https://travis-ci.org/BenLangmead/bowtie2.svg?branch=master)](https://travis-ci.org/BenLangmead/bowtie2) -->
 [![License: GPL v3](https://img.shields.io/badge/license-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 <!--badges: end -->

doc/manual.html

@@ -53,6 +53,8 @@ <h1 class="title">Bowtie 2 Manual</h1>
 <li><a href="#building-with-libsais-support"
 id="toc-building-with-libsais-support">Building with libsais
 support</a></li>
+<li><a href="#building-with-cmake" id="toc-building-with-cmake">Building
+with CMake</a></li>
 </ul></li>
 <li><a href="#adding-to-path" id="toc-adding-to-path">Adding to
 PATH</a></li>
@@ -384,6 +386,12 @@ <h3 id="building-with-libsais-support">Building with libsais
 <p>Finally, building the build executable: * with OpenMP support --
 <code>[g]make bowtie2-build-s USE_SAIS_OPENMP=1</code> * without OpenMP
 support -- <code>[g]make bowtie2-build-s USE_SAIS=1</code></p>
+<h3 id="building-with-cmake">Building with CMake</h3>
+<p>To build Bowtie2 with SRA and libsais support issue the following
+command: *
+<code>cmake . -D USE_SRA=1 -D USE_SAIS=1 &amp;&amp; cmake --build .</code></p>
+<p>CMake will take care of building and linking against the specified
+dependencies.</p>
 <h2 id="adding-to-path">Adding to PATH</h2>
 <p>By adding your new Bowtie 2 directory to your <a
 href="http://en.wikipedia.org/wiki/PATH_(variable)">PATH environment

doc/website/manual.ssi

@@ -12,7 +12,16 @@ Bowtie 2?</a></li>
 Bowtie 2</a>
 <ul>
 <li><a href="#building-from-source"
-id="toc-building-from-source">Building from source</a></li>
+id="toc-building-from-source">Building from source</a>
+<ul>
+<li><a href="#building-with-sra-support"
+id="toc-building-with-sra-support">Building with SRA support</a></li>
+<li><a href="#building-with-libsais-support"
+id="toc-building-with-libsais-support">Building with libsais
+support</a></li>
+<li><a href="#building-with-cmake" id="toc-building-with-cmake">Building
+with CMake</a></li>
+</ul></li>
 <li><a href="#adding-to-path" id="toc-adding-to-path">Adding to
 PATH</a></li>
 </ul></li>
@@ -307,11 +316,48 @@ dependency management. Running
 a series of commands that will: 1. download zstd and zlib 2. compile
 them as static libraries 3. link the resulting libraries to the compiled
 Bowtie 2 binaries</p>
+<h3 id="building-with-sra-support">Building with SRA support</h3>
 <p>As of version 2.3.5 bowtie2 now supports aligning SRA reads.
 Prepackaged builds will include a package that supports SRA. If you're
 building bowtie2 from source please make sure that the Java runtime is
 available on your system. You can then proceed with the build by running
 <code>make sra-deps &amp;&amp; make USE_SRA=1</code>.</p>
+<h3 id="building-with-libsais-support">Building with libsais
+support</h3>
+<p>As of version 2.5.3 <code>bowtie2</code> supports building indexes
+using the SAIS algorithm provided by <a
+href="https://github.com/IlyaGrebnov/libsais">libsais</a>. SAIS is a
+state-of-the-art suffix array construction algorithm that will
+bring-forth a significant speed-up to the overall index building
+process. There is, however, the downside of a significant increase in
+memory usage compared to the persistent blockwise algorithm that
+<code>bowtie2-build</code> uses by default. When using SAIS small
+indexes can be built for inputs up to 2GB. The
+<code>bowtie2-build</code> wrapper will help determine the appropriate
+index type for uncompressed and gzipped inputs.</p>
+<p>To build <code>bowtie2-build</code> with <a
+href="https://github.com/IlyaGrebnov/libsais">libsais</a> first make
+sure that the libsais submodule is available. This can be done in one of
+the following ways: * first time cloning bowtie2 --
+<code>git clone --recursive https://github.com/BenLangmead/bowtie2.git</code>
+* existing checkout of bowtie2 --
+<code>git submodule init &amp;&amp; git submodule update</code></p>
+<p>Issue the following command line to build libsais: * with OpenMP
+support -- <code>[g]make libsais USE_SAIS_OPENMP=1</code> * without
+OpenMP support -- <code>[g]make libsais USE_SAIS=1</code></p>
+<p>The choice of using OpenMP will determine whether or not the
+algorithm runs multithreaded. The [<code>-p/--threads</code>] argument
+to <code>bowtie2-build</code> will be ignored when libsais is compiled
+without OpenMP support.</p>
+<p>Finally, building the build executable: * with OpenMP support --
+<code>[g]make bowtie2-build-s USE_SAIS_OPENMP=1</code> * without OpenMP
+support -- <code>[g]make bowtie2-build-s USE_SAIS=1</code></p>
+<h3 id="building-with-cmake">Building with CMake</h3>
+<p>To build Bowtie2 with SRA and libsais support issue the following
+command: *
+<code>cmake . -D USE_SRA=1 -D USE_SAIS=1 &amp;&amp; cmake --build .</code></p>
+<p>CMake will take care of building and linking against the specified
+dependencies.</p>
 <h2 id="adding-to-path">Adding to PATH</h2>
 <p>By adding your new Bowtie 2 directory to your <a
 href="http://en.wikipedia.org/wiki/PATH_(variable)">PATH environment
@@ -1136,13 +1182,12 @@ also set.</p>
 <pre><code>-F k:&lt;int&gt;,i:&lt;int&gt;</code></pre>
 </td>
 <td>
-Reads are substrings (k-mers) extracted from a FASTA file
-<code>&lt;s&gt;</code>. Specifically, for every reference sequence in
-FASTA file <code>&lt;s&gt;</code>, Bowtie 2 aligns the k-mers at offsets
-1, 1+i, 1+2i, ... until reaching the end of the reference. Each k-mer is
-aligned as a separate read. Quality values are set to all Is (40 on
-Phred scale). Each k-mer (read) is given a name like
-<code>&lt;sequence&gt;_&lt;offset&gt;</code>, where
+Reads are substrings (k-mers) extracted from a FASTA file. Specifically,
+for every reference sequence in the FASTA file, Bowtie 2 aligns the
+k-mers at offsets 1, 1+i, 1+2i, ... until reaching the end of the
+reference. Each k-mer is aligned as a separate read. Quality values are
+set to all Is (40 on Phred scale). Each k-mer (read) is given a name
+like <code>&lt;sequence&gt;_&lt;offset&gt;</code>, where
 <code>&lt;sequence&gt;</code> is the name of the FASTA sequence it was
 drawn from and <code>&lt;offset&gt;</code> is its 0-based offset of
 origin with respect to the sequence. Only single k-mers, i.e. unpaired

doc/website/recent_news.ssi

@@ -1,3 +1,19 @@
+<h2>Version 2.5.3 - Jan 11, 2024</h2>
+<h3 id="bowtie2">bowtie2</h3>
+<ul>
+  <li>Fixed an issue causing <code>bowtie2</code>'s memory usage to increase over time.</li>
+  <li>Fixed an issue causing <code>bowtie2</code> to crash when processing eempty FASTQ records.</li>
+  <li>Fixed an issue causing <code>bowtie2</code> to erroneously treat <code><a href="manual.shtml#bowtie2-options-f">-f</a></code>
+      and <code><a href="manual.shtml#bowtie2-options-F">-F</a></code> as mutually exclusive.</li>
+</ul>
+<h3 id="bowtie2-build">bowtie2-build</h3>
+<ul>
+  <li>Add optional support for <code><a href="https://github.com/IlyaGrebnov/libsais">libsais</a></code>
+      to <code>bowtie2-build</code> for faster index building.</li>
+  N.B. -- small indexes are capped at <em>2GB</em> when using <code>libsais</code> as opposed to <em>4GB</em> when using
+  the default blockwise algorithm. See <a href="manual.shtml#building-from-source">MANUAL</a> for details.
+</ul>
+
 <h2>Version 2.5.2 - Oct 13, 2023</h2>
 <h3 id="bowtie2">bowtie2</h3>
 <ul>

doc/website/rhsidebar.ssi

@@ -18,10 +18,10 @@
         </tr>
       <tr>
       <td>
-        <a href="https://sourceforge.net/projects/bowtie-bio/files/bowtie2/2.5.2">Bowtie2 v2.5.2</a>
+        <a href="https://sourceforge.net/projects/bowtie-bio/files/bowtie2/2.5.3">Bowtie2 v2.5.3</a>
       </td>
       <td align="right">
-        10/13/23&nbsp;
+        01/11/24&nbsp;
       </td>
       </tr>
       <tr>