Skip to content

Commit d3c5e7b

Browse files
ivan-aksamentovivan-aksamentov
committed
docs: format
1 parent 6b21bc5 commit d3c5e7b

File tree

1 file changed

+102
-101
lines changed

1 file changed

+102
-101
lines changed

‎docs/dev/developer-guide.md‎

Lines changed: 102 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ as well as to the `--help` text for each tool.
4545

4646
> 💡 We accept pull requests on GitHub. If you want to submit a new feature or a bug fix, then create a GitHub account, [make a fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) of the [origin repository `nextstrain/nextclade`](https://github.com/nextstrain/nextclade) and clone your forked repository instead. Refer to [GitHub documentation "Contributing to projects"](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) for more details.
4747
48-
> 💡 Make sure you [keep your local code up to date](https://github.com/git-guides/git-pull) with the origin repo, [especially if it's forked](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork).
48+
> 💡 Make sure you [keep your local code up to date](https://github.com/git-guides/git-pull) with the origin repo, [especially if it's forked](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork).
4949
5050
> 💡 If you are a member of Nextstrain team, then you don't need a fork and you can contribute directly to the origin repository. Still, in most cases, please submit pull requests for review, rather than pushing changes to major branches directly.
5151
@@ -76,56 +76,56 @@ as well as to the `--help` text for each tool.
7676

7777
The only supported Rust version is the one declared in [`rust-toolchain.toml`](https://github.com/nextstrain/nextclade/blob/master/rust-toolchain.toml) (currently **1.92.0**).
7878

79-
```bash
80-
# Install Rustup, the Rust version manager
81-
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
79+
```bash
80+
# Install Rustup, the Rust version manager
81+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
8282

83-
# Add Rust tools to the $PATH
84-
export PATH="$PATH:$HOME/.cargo/bin"
83+
# Add Rust tools to the $PATH
84+
export PATH="$PATH:$HOME/.cargo/bin"
8585

86-
# Check your installed versions
87-
rustc -V
88-
cargo -V
89-
rustup -V
90-
```
86+
# Check your installed versions
87+
rustc -V
88+
cargo -V
89+
rustup -V
90+
```
9191

9292
> ⚠️ Nextclade team doesn't have bandwidth to support Rust installations deviating from the [officially recommended steps](https://doc.rust-lang.org/book/ch01-01-installation.html) and Rust versions different from what is declared in [rust-toolchain.toml](https://github.com/nextstrain/nextclade/blob/master/rust-toolchain.toml). If you install Rust from Linux package repositories, Homebrew, Conda etc., things may or may not work, or they may work but produce wrong results. Nextclade team doesn't have bandwidth to try every platform and config, so if you decide to go unofficial route, then you are on your own. But feel free to open pull requests if fixes are necessary to make your setup work.
9393
9494
> 💡 Note, Rustup allows to install multiple versions of Rust and to switch between them. This repository contains a [rust-toolchain.toml](https://github.com/nextstrain/nextclade/blob/master/rust-toolchain.toml) file, which describes which version of Rust is currently in use by Nextclade official build. Cargo and Rustup should be able to [pick it up automatically](https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file), install the required toolchain and use it when you type `cargo` commands. Any other versions of Rust toolchain are not supported.
9595
9696
4. Prepare environment variables (once). They configure Nextclade build-time settings. Optionally adjust the variables in the `.env` file to your needs.
9797

98-
```bash
99-
cp .env.example .env
100-
```
98+
```bash
99+
cp .env.example .env
100+
```
101101

102102
5. Build and run Nextclade CLI in debug mode (convenient for development - faster to build, slow to run, has more debug info in the executable, error messages are more elaborate):
103103

104-
```bash
105-
# (Re-)build Nextclade in debug mode.
106-
# By default, the resulting executable will be in `target/debug/nextclade`.
107-
cargo build --bin=nextclade
108-
109-
# (Re-)build Nextclade in debug mode and run `nextclade --help` to print
110-
# Nextclade CLI main help screen. The arguments after the `--` are passed
111-
# to nextclade executable, as if you'd run it directly.
112-
# Refer to Nextclade user documentation for explanation of arguments.
113-
cargo run --bin=nextclade -- --help
114-
115-
# (Re-)build Nextclade in debug mode and use it to download a dataset to
116-
# `data_dev/` directory.
117-
cargo run --bin=nextclade -- dataset get \
118-
--name='sars-cov-2' \
119-
--output-dir='data_dev/sars-cov-2'
120-
121-
# (Re-)build Nextclade in debug mode and run the analysis using the
122-
# dataset we just downloaded (to `data_dev/`) and output results to
123-
# the `out/` directory.
124-
cargo run --bin=nextclade -- run \
125-
'data_dev/sars-cov-2/sequences.fasta' \
126-
--input-dataset='data_dev/sars-cov-2/' \
127-
--output-all='out/'
128-
```
104+
```bash
105+
# (Re-)build Nextclade in debug mode.
106+
# By default, the resulting executable will be in `target/debug/nextclade`.
107+
cargo build --bin=nextclade
108+
109+
# (Re-)build Nextclade in debug mode and run `nextclade --help` to print
110+
# Nextclade CLI main help screen. The arguments after the `--` are passed
111+
# to nextclade executable, as if you'd run it directly.
112+
# Refer to Nextclade user documentation for explanation of arguments.
113+
cargo run --bin=nextclade -- --help
114+
115+
# (Re-)build Nextclade in debug mode and use it to download a dataset to
116+
# `data_dev/` directory.
117+
cargo run --bin=nextclade -- dataset get \
118+
--name='sars-cov-2' \
119+
--output-dir='data_dev/sars-cov-2'
120+
121+
# (Re-)build Nextclade in debug mode and run the analysis using the
122+
# dataset we just downloaded (to `data_dev/`) and output results to
123+
# the `out/` directory.
124+
cargo run --bin=nextclade -- run \
125+
'data_dev/sars-cov-2/sequences.fasta' \
126+
--input-dataset='data_dev/sars-cov-2/' \
127+
--output-all='out/'
128+
```
129129

130130
The `cargo run` command automatically performs the `cargo build` command if there are code changes.
131131

@@ -135,18 +135,18 @@ as well as to the `--help` text for each tool.
135135
136136
6. Build and run Nextclade CLI in release mode (slow to build, fast to run, very little debug info):
137137

138-
```bash
139-
# Build Nextclade in release mode.
140-
# By default, the resulting executable will be in `target/release/nextclade`.
141-
cargo build --bin=nextclade --release
142-
143-
# Run Nextclade release binary
144-
./target/release/nextclade run \
145-
'data_dev/sars-cov-2/sequences.fasta' \
146-
--input-dataset='data_dev/sars-cov-2/' \
147-
--output-all='out/'
148-
149-
```
138+
```bash
139+
# Build Nextclade in release mode.
140+
# By default, the resulting executable will be in `target/release/nextclade`.
141+
cargo build --bin=nextclade --release
142+
143+
# Run Nextclade release binary
144+
./target/release/nextclade run \
145+
'data_dev/sars-cov-2/sequences.fasta' \
146+
--input-dataset='data_dev/sars-cov-2/' \
147+
--output-all='out/'
148+
149+
```
150150

151151
> 💡 Debug builds are incremental, i.e. only the files that have changed since the last build are compiled, which is much faster that full build. But release builds are always full builds, with additional optimization passes, so they take much more time. If you need to quickly iterate on features, then use debug builds. If you are measuring performance, or building binaries for the actual daily usage, always use release builds.
152152
@@ -167,14 +167,14 @@ Note that there is no actual programmable backend server. Nextclade Web is a sta
167167

168168
Clone Nextclade git repository:
169169

170-
```bash
171-
git clone https://github.com/nextstrain/nextclade
172-
cd nextclade
173-
```
170+
```bash
171+
git clone https://github.com/nextstrain/nextclade
172+
cd nextclade
173+
```
174174

175175
> 💡 We accept pull requests on GitHub. If you want to submit a with new feature or a bug fixe, then make a GitHub account, [make a fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) of the [origin Nextclade repository](https://github.com/nextstrain/nextclade) and clone your forked repository instead. Refer to [GitHub documentation "Contributing to projects"](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) for more details.
176176
177-
> 💡 Make sure you [keep your local code up to date](https://github.com/git-guides/git-pull) with the origin repo, [especially if it's forked](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork).
177+
> 💡 Make sure you [keep your local code up to date](https://github.com/git-guides/git-pull) with the origin repo, [especially if it's forked](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork).
178178
179179
> 💡 If you are a member of Nextstrain team, then you don't need a fork and you can contribute directly to the origin repository. Still, in most cases, please submit pull requests for review, rather than pushing changes to branches directly.
180180
@@ -184,19 +184,19 @@ Note that there is no actual programmable backend server. Nextclade Web is a sta
184184

185185
Install Node.js from [nodejs.org](https://nodejs.org), or using [nvm](https://github.com/nvm-sh/nvm):
186186

187-
```bash
188-
cd nextclade/
189-
nvm install
190-
nvm use
191-
node --version
192-
```
187+
```bash
188+
cd nextclade/
189+
nvm install
190+
nvm use
191+
node --version
192+
```
193193

194194
Install Bun (version **1.2.14** recommended) from [bun.sh](https://bun.sh):
195195

196-
```bash
197-
curl -fsSL https://bun.sh/install | bash
198-
bun --version
199-
```
196+
```bash
197+
curl -fsSL https://bun.sh/install | bash
198+
bun --version
199+
```
200200

201201
> ⚠️ Nextclade team doesn't have bandwidth to support Node.js installations from Linux package repositories, Homebrew, Conda, as well as versions of Node.js which are not the same as the one currently declared in the [`.nvmrc`](https://github.com/nextstrain/nextclade/blob/master/.nvmrc), and everything else deviating from the recommended setup. If you decide to go that route - things may or may not work - you are on your own. But feel free to open pull requests if fixes are necessary to make your setup work.
202202
@@ -241,30 +241,30 @@ Note that there is no actual programmable backend server. Nextclade Web is a sta
241241

242242
5. Prepare environment variables (once). They configure Nextclade build-time settings. Optionally adjust the variables in the `.env` file to your needs.
243243

244-
```bash
245-
cp .env.example .env
246-
```
244+
```bash
245+
cp .env.example .env
246+
```
247247

248248
6. Install WebAssembly toolchain (once)
249249

250250
The following versions are pinned for build reproducibility:
251251

252-
| Tool | Version |
253-
|------|---------|
254-
| wasm-pack | 0.13.1 |
252+
| Tool | Version |
253+
| ---------------- | ------- |
254+
| wasm-pack | 0.13.1 |
255255
| wasm-bindgen-cli | 0.2.106 |
256-
| binaryen | 125 |
256+
| binaryen | 125 |
257257

258-
```bash
259-
# Install wasm-pack
260-
cargo install wasm-pack@0.13.1 --locked
258+
```bash
259+
# Install wasm-pack
260+
cargo install wasm-pack@0.13.1 --locked
261261

262-
# Install wasm-bindgen-cli (must match the version in Cargo.toml)
263-
cargo install wasm-bindgen-cli@0.2.106 --locked
262+
# Install wasm-bindgen-cli (must match the version in Cargo.toml)
263+
cargo install wasm-bindgen-cli@0.2.106 --locked
264264

265-
# Add WebAssembly compilation target
266-
rustup target add wasm32-unknown-unknown
267-
```
265+
# Add WebAssembly compilation target
266+
rustup target add wasm32-unknown-unknown
267+
```
268268

269269
<details>
270270
<summary>🐧 Install binaryen on Linux</summary>
@@ -291,21 +291,21 @@ Note that there is no actual programmable backend server. Nextclade Web is a sta
291291

292292
7. Install NPM dependencies (once)
293293

294-
```bash
295-
cd packages/nextclade-web
296-
bun install
297-
```
294+
```bash
295+
cd packages/nextclade-web
296+
bun install
297+
```
298298

299299
> ⚠️ Nextclade uses `bun` to manage NPM dependencies. While you could try `npm` or other tools instead, we don't support this.
300300
301301
8. Build the WebAssembly module
302302

303-
```bash
304-
cd packages/nextclade-web
305-
bun wasm-prod
306-
```
303+
```bash
304+
cd packages/nextclade-web
305+
bun wasm-prod
306+
```
307307

308-
This step might take a lot of time. The WebAssembly module and accompanying Typescript code should be been generated into `packages/nextclade-web/src/gen/`. The web application should be able to find it there.
308+
This step might take a lot of time. The WebAssembly module and accompanying Typescript code should be been generated into `packages/nextclade-web/src/gen/`. The web application should be able to find it there.
309309

310310
Repeat this step every time you are changing Rust code.
311311

@@ -315,31 +315,31 @@ Note that there is no actual programmable backend server. Nextclade Web is a sta
315315

316316
The development version can be built using:
317317

318-
```bash
319-
cd packages/nextclade-web
320-
bun dev
321-
```
318+
```bash
319+
cd packages/nextclade-web
320+
bun dev
321+
```
322322

323323
This runs Next.js dev server (continuously). Open `http://localhost:3000/` in the browser. Typescript code changes should trigger automatic rebuild and fast refresh of the app in the browser - no dev server restart is typically necessary.
324324

325325
Note that changes in Rust code (the algorithms) are not picked up automatically and the requirement rebuilding the WebAssembly module manually (as explained above). Once you rebuild the WebAssembly module in a separate terminal instance, the dev server should pick up the changes in the algorithms - no dev server restart is necessary.
326326

327327
10. Build and serve the production version of the web app locally
328328

329-
Alternatively, the optimized ("production") version of the web app can be built and (optionally) served with
329+
Alternatively, the optimized ("production") version of the web app can be built and (optionally) served with
330330

331331
```bash
332332
bun prod:build
333333
bun prod:serve
334334
```
335335

336-
Open `http://localhost:8080/` in the browser.
336+
Open `http://localhost:8080/` in the browser.
337337

338-
The resulting HTML, CSS, JS and WASM files should be available under `packages/nextclade-web/.build/production/web/`. This is the "web root" of the application. All files required to deploy and serve Nextclade Web are there.
338+
The resulting HTML, CSS, JS and WASM files should be available under `packages/nextclade-web/.build/production/web/`. This is the "web root" of the application. All files required to deploy and serve Nextclade Web are there.
339339

340-
The production build does not have automatic rebuild and reload. You need to do full rebuild on every code change - both the WebAssembly module and then the web app.
340+
The production build does not have automatic rebuild and reload. You need to do full rebuild on every code change - both the WebAssembly module and then the web app.
341341

342-
The `bun prod:serve` command runs a simple static file web server. But the produced files can be served using any static file web server (Apache, Nginx, Caddy, Express, etc.), static file hosting services, or cloud services (AWS S3, Vercel, GitHub Pages, etc.). The official deployment uses AWS S3 + Cloudfront.
342+
The `bun prod:serve` command runs a simple static file web server. But the produced files can be served using any static file web server (Apache, Nginx, Caddy, Express, etc.), static file hosting services, or cloud services (AWS S3, Vercel, GitHub Pages, etc.). The official deployment uses AWS S3 + Cloudfront.
343343

344344
### Internationalization (translation)
345345

@@ -441,7 +441,6 @@ For routine development, it is recommended to configure your text editor to see
441441
442442
(these instructions can go out of date with time, so make sure you check Jetbrains docs for what's latest and greatest)
443443
444-
445444
> Install [Intellij Rust plugin](https://intellij-rust.github.io/).
446445
>
447446
> In main menu, "File | Settings | Languages & Frameworks | Rust | External Linters", set "External tool" to "Clippy" and check the checkbox "Run external linter to analyze code on the fly".
@@ -523,7 +522,7 @@ Other branches are built in the context of GitHub pull requests. If you submit a
523522
Here is a list of environments:
524523
525524
| Nextclade repo branch | Nextclade Web domain name | Dataset server | Meaning |
526-
|-----------------------|----------------------------|--------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
525+
| --------------------- | -------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
527526
| release | clades.nextstrain.org | data.clades.nextstrain.org | Final release, targeting all end users |
528527
| staging | staging.nextstrain.org | data.staging.nextstrain.org | Staging release, for last-minute testing and fixes before a final release is made, to not block progress on master branch |
529528
| master | master.nextstrain.org | data.master.nextstrain.org | Main development branch - accumulates features and bug fixes from pull requests |
@@ -566,6 +565,7 @@ In all cases you need to have a dataset server directory ready (contained datase
566565
- Build a fresh dataset server directory as described in the [nextstrain/nextclade_data](https://github.com/nextstrain/nextclade_data) repo. At the time of writing it simply means to run `./scripts/rebuild` and to observe the `data_output/` directory created, containing the dataset files and associated index files
567566
568567
- Serve the output directory locally using any static file server. [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) should be enabled on the server. For example, using `serve` package from NPM:
568+
569569
```bash
570570
npx serve@latest --cors --listen=tcp://0.0.0.0:3001 data_output/
571571
```
@@ -575,6 +575,7 @@ In all cases you need to have a dataset server directory ready (contained datase
575575
```bash
576576
curl http://localhost:3001/index.json
577577
```
578+
578579
and to see some JSON when navigating to `http://localhost:3001/index.json` in a web browser.
579580

580581
### Temporarily use custom dataset server with Nextclade CLI

0 commit comments

Comments
 (0)