Merge branch 'slee/move-dev-quickstart-to-devmd' into 'release-v0.7'

Move developer quickstart and extend installation instructions

See merge request machine-learning/dorado!1033

Author: tijyojwad

DEV.md

@@ -1,6 +1,45 @@
-## Setup notes
+# Developer Quickstart
 
-Dorado requires CUDA 11.8 on linux platforms. If the system you are running on does not have CUDA 11.8 installed, and you do not have sudo privileges, you can install locally from a run file as follows:
+## Dependencies
+
+### Pre-commit
+
+The project uses pre-commit to ensure code is consistently formatted; you can set this up using pip:
+
+```bash
+$ pip install pre-commit
+$ pre-commit install
+```
+
+### Linux dependencies
+
+The following packages are necessary to build Dorado in a barebones environment (e.g. the official ubuntu:jammy Docker image).
+
+```
+$ apt-get update && apt-get install -y --no-install-recommends \
+        curl \
+        git \
+        ca-certificates \
+        build-essential \
+        libhdf5-dev \
+        libssl-dev \
+        libzstd-dev \
+        autoconf \
+        automake
+$ apt install gcc-9 g++-9 --no-install-recommends
+$ update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-9 60 --slave /usr/bin/g++ g++ /usr/bin/g++-9
+```
+
+This project requires `cmake 3.23` or higher. This can be installed via binary download from [cmake.org](https://cmake.org/download/) or using `python3-venv`: 
+
+```
+$ apt install python3-venv
+$ python3 -m venv venv
+$ . venv/bin/activate
+$ pip install "cmake>=3.23"
+```
+
+Dorado requires CUDA 11.8 on Linux platforms. If the system you are running on does not have CUDA 11.8 installed, and you do not have sudo privileges, you can install locally from a run file as follows:
 
 ```
 $ wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run
@@ -13,17 +52,18 @@ In this case, cmake should be invoked with `CUDAToolkit_ROOT` in order to tell t
 $ cmake -DCUDAToolkit_ROOT=~/dorado_deps/cuda11.8 -S . -B cmake-build
 ```
 
-Note that a [suitable NVIDIA driver](https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html#id3) will be required in order to run dorado.
+Note that a [suitable NVIDIA driver](https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html#id3) will be required in order to run Dorado.
+
+All other dependencies will be fetched automatically by the cmake build process.  
 
-All other dependencies will be fetched automatically by the cmake build process.
 
 If libtorch is already downloaded on the host system and you do not wish the build process to re-download it, you can specify `DORADO_LIBTORCH_DIR` to cmake, in order to specify where the build process should locate it.  For example:
 
 ```
 $ cmake -DDORADO_LIBTORCH_DIR=/usr/local/libtorch -S . -B cmake-build
 ```
 
-### OSX
+### OSX dependencies
 
 On OSX, version 2.69 of autoconf is required:
 
@@ -35,5 +75,25 @@ $ brew link autoconf@2.69
 
 The following other packages need to be available as well
 ```bash
-brew install openssl zstd
+$ brew install openssl zstd
+```
+
+### Clone and build
+
+```
+$ git clone https://github.com/nanoporetech/dorado.git dorado
+$ cd dorado
+$ cmake -S . -B cmake-build
+$ cmake --build cmake-build --config Release -j
+$ ctest --test-dir cmake-build
+```
+
+The `-j` flag will use all available threads to build Dorado and usage is around 1-2 GB per thread. If you are constrained
+by the amount of available memory on your system, you can lower the number of threads i.e.` -j 4`.
+
+After building, you can run Dorado from the build directory `./cmake-build/bin/dorado` or install it somewhere else on your
+system i.e. `/opt` *(note: you will need the relevant permissions for the target installation directory)*.
+
+```
+$ cmake --install cmake-build --prefix /opt
 ```

README.md

@@ -20,11 +20,27 @@ If you encounter any problems building or running Dorado, please [report an issu
 
 ## Installation
 
+First, download the relevant installer for your platform:
+
  - [dorado-0.7.0-linux-x64](https://cdn.oxfordnanoportal.com/software/analysis/dorado-0.7.0-linux-x64.tar.gz)
  - [dorado-0.7.0-linux-arm64](https://cdn.oxfordnanoportal.com/software/analysis/dorado-0.7.0-linux-arm64.tar.gz)
  - [dorado-0.7.0-osx-arm64](https://cdn.oxfordnanoportal.com/software/analysis/dorado-0.7.0-osx-arm64.zip)
  - [dorado-0.7.0-win64](https://cdn.oxfordnanoportal.com/software/analysis/dorado-0.7.0-win64.zip)
 
+Once the relevant `.tar.gz` or `.zip` archive is downloaded, extract the archive to your desired location.
+
+You can then call Dorado using the full path, for example:
+```
+$ /path/to/dorado-x.y.z-linux-x64/bin/dorado basecaller hac pod5s/ > calls.bam
+```
+
+Or you can add the bin path to your `$PATH` environment variable, and run with the `dorado` command instead, for example:
+```
+$ dorado basecaller hac pod5s/ > calls.bam
+```
+
+See [DEV.md](DEV.md) for details about building Dorado for development.
+
 ## Platforms
 
 Dorado is heavily-optimised for Nvidia A100 and H100 GPUs and will deliver maximal performance on systems with these GPUs.
@@ -408,56 +424,6 @@ Here are a few examples of model complexes:
 | sup,5mCG_5hmCG,6mA  | Latest compatible **sup** model and latest compatible **5mCG_5hmCG** and **6mA** modifications models |
 
 
-## Developer quickstart
-
-### Linux dependencies
-
-The following packages are necessary to build Dorado in a barebones environment (e.g. the official ubuntu:jammy docker image).
-
-```
-$ apt-get update && apt-get install -y --no-install-recommends \
-        curl \
-        git \
-        ca-certificates \
-        build-essential \
-        nvidia-cuda-toolkit \
-        libhdf5-dev \
-        libssl-dev \
-        libzstd-dev \
-        cmake \
-        autoconf \
-        automake
-```
-
-### Clone and build
-
-```
-$ git clone https://github.com/nanoporetech/dorado.git dorado
-$ cd dorado
-$ cmake -S . -B cmake-build
-$ cmake --build cmake-build --config Release -j
-$ ctest --test-dir cmake-build
-```
-
-The `-j` flag will use all available threads to build Dorado and usage is around 1-2 GB per thread. If you are constrained
-by the amount of available memory on your system, you can lower the number of threads i.e.` -j 4`.
-
-After building, you can run Dorado from the build directory `./cmake-build/bin/dorado` or install it somewhere else on your
-system i.e. `/opt` *(note: you will need the relevant permissions for the target installation directory)*.
-
-```
-$ cmake --install cmake-build --prefix /opt
-```
-
-### Pre-commit
-
-The project uses pre-commit to ensure code is consistently formatted; you can set this up using pip:
-
-```bash
-$ pip install pre-commit
-$ pre-commit install
-```
-
 ## Troubleshooting Guide
 
 ### Library Path Errors