Merge pull request #3320 from eseiler/doc/update

[DOC] Update

Author: eseiler

CHANGELOG.md

@@ -30,17 +30,40 @@ The following API changes should be documented as such:
 If possible, provide tooling that performs the changes, e.g. a shell-script.
 -->
 
-# 3.3.1
+# 3.4.0
 
 ## New features
 
+#### I/O
+  * `seqan3::sam_file_input` now accepts user-defined tags ([\#3256](https://github.com/seqan/seqan3/pull/3256)).
+
 ## Notable Bug-fixes
 
+#### Alphabet
+  * Resolved an issue that prevented proper conversion, most notably in conjunction with `seqan3::bitpacked_sequence`
+    ([\#3268](https://github.com/seqan/seqan3/pull/3268)).
+
+#### Alignment
+  * Fixed an issue that caused incorrect begin and end positions for banded alignments
+    ([\#3269](https://github.com/seqan/seqan3/pull/3269)).
+
+#### I/O
+  * `seqan3::sam_file_output` now takes ownership of the given reference information
+    ([\#3300](https://github.com/seqan/seqan3/pull/3300)).
+
 ## API changes
 
+#### Compiler
+  * Supported compiler:
+    * GCC 12, 13, 14
+    * Clang 17, 18, 19
+    * IntelOneAPI/IntelLLVM 2024.0
+
 #### Dependencies
   * We now use Doxygen version 1.9.8 to build our documentation ([\#3197](https://github.com/seqan/seqan3/pull/3197)).
-  * We bumped the minimal CMake version to 3.5 ([\#3223](https://github.com/seqan/seqan3/pull/3223)).
+  * We bumped the minimal CMake version to 3.20 ([\#3314](https://github.com/seqan/seqan3/pull/3314)).
+  * Dependencies are now managed via CPM instead of submodules ([\#3328](https://github.com/seqan/seqan3/pull/3328)).
+  * The `build_system` directory was renamed to `cmake` ([\#3292](https://github.com/seqan/seqan3/pull/3292)).
 
 # 3.3.0
 

README.md

@@ -72,8 +72,10 @@ Please see the [online documentation](https://docs.seqan.de/seqan3/main_user/) f
 
 |                   | requirement                                          | version  | comment                                     |
 |-------------------|------------------------------------------------------|----------|---------------------------------------------|
-|**compiler**       | [GCC](https://gcc.gnu.org)                           | ≥ 11     | no other compiler is currently supported!   |
-|**build system**   | [CMake](https://cmake.org)                           | ≥ 3.5    | optional, but recommended                   |
+|**compiler**       | [GCC](https://gcc.gnu.org)                           | ≥ 12     |                                             |
+|                   | [Clang](https://clang.llvm.org)                      | ≥ 17     | tested with `-stdlib=libc++`                |
+|                   | [IntelOneAPI]()                                      | ≥ 2024.0 |                                             |
+|**build system**   | [CMake](https://cmake.org)                           | ≥ 3.20   | optional, but recommended                   |
 |**required libs**  | [SDSL](https://github.com/xxsds/sdsl-lite)           | ≥ 3.0.3  |                                             |
 |**optional libs**  | [cereal](https://github.com/USCiLab/cereal)          | ≥ 1.3.1  | required for serialisation and CTD support  |
 |                   | [zlib](https://github.com/madler/zlib)               | ≥ 1.2    | required for `*.gz` and `.bam` file support |
@@ -85,21 +87,3 @@ We recommend that you use CMake to build your project:
 
   * [Setup-Tutorial](https://docs.seqan.de/seqan3/main_user/setup.html)
   * Using CMake guarantees that all optional dependencies are automatically detected and activated.
-
-Quick-Setup without CMake:
-
-  * Clone the repository: `git clone https://github.com/seqan/seqan3.git`
-  * Add the following to your compiler invocation:
-    * the include directories of SeqAn and its dependencies
-    * C++20 mode
-    * Macros indicating the presence of zlib and bzip2 (set only if actually available in your paths!)
-  * The command could look like this:
-```sh
-g++-11 -O3 -DNDEBUG -Wall -Wextra                               \
-    -std=c++20                                                  \
-    -I       /path/to/seqan3/include                            \
-    -isystem /path/to/sdsl-lite/include                         \
-    -DSEQAN3_HAS_ZLIB=1 -DSEQAN3_HAS_BZIP2=1                    \
-    -lz -lbz2 -pthread                                          \
-  your_file.cpp
-```

doc/setup/quickstart_cmake/index.md

@@ -17,31 +17,34 @@ works.
 
 # Software
 Requirements:
-  - gcc >= 11
-  - cmake >= 3.5
+  - gcc >= 12 or clang >=17 or IntelOneAPI >= 2024.0
+  - cmake >= 3.20
   - git
 
-## Installing GCC
+## Installing a compiler
 
-SeqAn requires GCC >= 11. Current versions of LLVM/Clang and VisualStudio/MSVC are **not yet supported**.
-We will briefly explain how to install GCC-11 (or the latest GCC if such an option is available) on some popular
-operating systems. We recommend using the latest version of GCC available. For more information, refer to your
-operating system's documentation.
+VisualStudio/MSVC is **not yet supported**.
+We will briefly explain how to install a compiler on some popular operating systems.
+We recommend using the latest version of the compiler.
+For more information, refer to your operating system's documentation.
 
-### Linux
+### GCC
+
+#### Linux
 <div class="tabbed">
-- <b class="tab-title">Ubuntu >= 22.04</b>
+- <b class="tab-title">Ubuntu without PPA</b>
 ```bash
-# Installs default compiler version (gcc-11 for Ubuntu 22.04).
-sudo apt install g++
-# To install gcc-12, follow instructions for Ubuntu < 22.04.
+# Ubuntu 24.04
+sudo apt install g++-14
+# Ubuntu 22.04
+sudo apt install g++-12
 ```
-- <b class="tab-title">Ubuntu < 22.04</b>
+- <b class="tab-title">Ubuntu with PPA</b>
 ```bash
 sudo add-apt-repository --no-update --yes ppa:ubuntu-toolchain-r/ppa
 sudo add-apt-repository --no-update --yes ppa:ubuntu-toolchain-r/test
 sudo apt-get update
-sudo apt install g++-11
+sudo apt install g++-14
 ```
 - <b class="tab-title">Using conda</b>
 To avoid interference with system packages, we recommend creating a new environment when using conda.
@@ -54,15 +57,42 @@ and deactivated via `conda deactivate`.
 
 </div>
 
-### macOS
+#### macOS
 <div class="tabbed">
 - <b class="tab-title">Using Homebrew</b>
 ```bash
-brew install gcc@11
+brew install gcc@14
 ```
 - <b class="tab-title">Using Macports</b>
 ```bash
-sudo port install gcc11
+sudo port install gcc14
+```
+
+</div>
+
+### Clang
+
+#### Linux
+<div class="tabbed">
+- <b class="tab-title">Ubuntu 24.04</b>
+```bash
+# Ubuntu 24.04
+sudo apt install clang-18
+```
+- <b class="tab-title">Ubuntu with PPA</b>
+Refer to https://apt.llvm.org/
+
+</div>
+
+#### macOS
+<div class="tabbed">
+- <b class="tab-title">Using Homebrew</b>
+```bash
+brew install llvm@19
+```
+- <b class="tab-title">Using Macports</b>
+```bash
+sudo port install clang-19
 ```
 
 </div>
@@ -85,7 +115,7 @@ hours of use per month, which is plenty for our tutorials. A GitHub account is r
 </div>
 <br>
 \attention After installing, `g++ --version` should print the desired GCC version.
-           If not, you may have to use, for example, `g++-11 --version` or even specify the full path to your compiler.
+           If not, you may have to use, for example, `g++-14 --version` or even specify the full path to your compiler.
 
 Similarly, you may need to install CMake and git, e.g. `apt install cmake git`.
 
@@ -175,7 +205,7 @@ of errors easier. `Debug` is suitable for contributors, and we recommend using i
 \remark Depending on the standard C++ compiler on your system, you may need to specify the compiler via
 `-DCMAKE_CXX_COMPILER=`, for example:
 ```bash
-cmake -DCMAKE_CXX_COMPILER=/path/to/executable/g++-11 ../source
+cmake -DCMAKE_CXX_COMPILER=/path/to/executable/g++-14 ../source
 ```
 
 # Adding a new source file to your project
@@ -212,6 +242,25 @@ add_executable (my_app my_app.cpp)
 target_link_libraries (my_app PUBLIC seqan3::seqan3)
 ```
 
+# Including SeqAn3 as external project with CPM (recommended)
+
+See https://github.com/cpm-cmake/CPM.cmake for install instructions.
+
+```cmake
+cmake_minimum_required (VERSION 3.20...3.31)
+
+project (my_app LANGUAGES CXX VERSION 1.0.0)
+
+include (cmake/CPM.cmake)
+
+CPMAddPackage("gh:seqan/seqan3@3.4.0")
+
+add_executable (my_app my_app.cpp)
+
+# Set up everything needed to use SeqAn3 with my_app:
+target_link_libraries (my_app PUBLIC seqan3::seqan3)
+```
+
 # Encountered issues
 
 * **Using conda's gcc package:** ``/usr/lib/x86_64-linux-gnu/libstdc++.so.6: version 'CXXABI_1.3.11' not found``<br>