Skip to content

Commit

Permalink
doc: update some dev documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
kleinesfilmroellchen committed Oct 16, 2024
1 parent f804fed commit c31afc9
Showing 1 changed file with 12 additions and 10 deletions.
22 changes: 12 additions & 10 deletions doc/src/dev/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Over time, spcasm has evolved from "just an SPC700 assembler" to a whole toolcha
- The `spcasm-web` crate contains WebAssembly APIs and a browser frontend allowing the assembler to run in the browser.
- The `sals` crate contains the **s**pc**a**sm **l**anguage **s**erver, an experimental language server for SPC-700 assembly.
- The `sapemu` crate contains the (WIP) cycle-accurate S-APU emulator.
- The `spcfile` crate contains a (WIP) generic .spc file format parser and writer. This is a common library of `spcasm` (for .spc writing) and `sapemu` (for .spc playback).
- The `spcfile` crate contains a generic .spc file format parser and writer. This is a common library of `spcasm` (for .spc writing) and `sapemu` (for .spc playback).
- The `doc` folder contains [mdbook](https://rust-lang.github.io/mdBook/)-based documentation. You can read this documentation directly on GitHub, or build a statically servable website from it with mdbook.

spcasm itself contains by far the most code, and [its entire documentation is available online](../api/spcasm/index.html).
Expand All @@ -26,9 +26,9 @@ spcasm itself contains by far the most code, and [its entire documentation is av

> `$ just spcasm`
spcasm is written in Rust (2021 edition). Due to the use of many (really cool!) unstable features, it can only be compiled with a Rust nightly compiler. The minimum supported Rust version (MSRV) can be found in Cargo.toml.
spcasm is written in Rust (2021 edition). Due to the use of many (really cool!) unstable features, it can only be compiled with a Rust nightly compiler.

Because of `rust-toolchain.toml`, the nightly toolchain should automatically be selected if you run any Rustup-based command (like `cargo` or `rustc`).
Because of `rust-toolchain.toml`, the nightly toolchain should automatically be selected if you run any Rustup-based command (like `cargo` or `rustc`). This file also pins a known working release of the nightly compiler, which is updated occasionally. (I try to update to the newest nightly after most stable releases.)

The standard binary is the assembler `spcasm` itself. There is an additional binary target `brr`, a BRR encoder and decoder with additional interactive functionality. Both require the `binaries` feature. The other crates have their own (singular) targets.

Expand All @@ -40,7 +40,7 @@ The crate has the following features:

- `binaries`: Enable the two binaries `spcasm` and `brr` and their specific dependencies. If you want to run non-CLI tests or use spcasm as a library, this is not necessary, therefore although it is a default feature, it can be disabled.

If you want to create an optimized build, please compile with the `spcasm-fastrelease` profile; the standard `release` profile needs to be reserved for `wasm-pack` as it is too inflexible at the moment.
If you want to create an optimized build, please compile with the `spcasm-fastrelease` profile; the standard `release` profile needs to be reserved for spcasm-web as it is too inflexible at the moment.

There's further ways of fiddling with the build config:

Expand All @@ -49,19 +49,19 @@ There's further ways of fiddling with the build config:

### Creating a release

The release process requires `just` and a Windows machine with WSL, and it can take many minutes to run the multitude of compilations and checks.
The release process requires `just`, and it can take many minutes to run the multitude of compilations and checks.

```shell
# Ensure up-to-date toolchains.
$ rustup update && wsl rustup update
# Ensure up-to-date toolchain.
$ rustup update

$ just clean
$ just release $version
```

Towards the end, the process will run the released binaries to show their version information. Check that this version information is up-to-date, and if not, update the version information in the main Cargo.toml and run the release again.

Finally, create a GitHub release and attach the two archives and four binaries from the `spcasm-$version` folder that was created. Make sure that the main branch from which the release build was run is up-to-date in the repository before releasing.
Release binaries are automatically compiled and uploaded when a GitHub release is created.

### Experimental profile-guided optimization builds

Expand All @@ -85,7 +85,7 @@ Working with the WebAssembly bindings and webpage is quite straightforward, but

### `sapemu`

_Important note: sapemu is *very* work-in-progress. The current executable serves the sole purpose of verifying emulator behavior and is not at all practical or useful to end users. The plan is to eventually add a GUI frontend to sapemu. Only concern yourself with sapemu at the present stage if you want to help with completing it._
_Important note: sapemu is *very* work-in-progress. The current executable serves the sole purpose of verifying emulator behavior and is not at all practical or useful to end users. The plan is to eventually add a GUI frontend to sapemu, as well as audio playback and WAV file output. Only concern yourself with sapemu at the present stage if you want to help with completing it._

sapemu contains a work-in-progress cycle-accurate emulator of the entire SNES sound system, technically referred to as the S-APU (therefore the portmanteau name). The emulator binary has a WIP command-line interface (changes may happen at any time, and it is likely that a major revamp will happen before sapemu's first inclusion in releases) that provides help output with `--help`, so `cd sapemu && cargo run -- --help`. The binary can print a lot of logging information to the console if you use high verbosity levels, so beware.

Expand All @@ -99,6 +99,8 @@ sapemu's functionality is currently mostly verified through tests. We use the te

Since spcasm provides a library crate, it can be reused in other crates. This is primarily important for the other crates in the spcasm project, like `spcasm-web` or `sals`. However, since you can use Rust crates from any GitHub repository (see the Cargo documentation), it is fairly easy to use spcasm as a library in an external project.

However, an important caveat applies: **spcasm provides no API stability guarantees**, not even according to semver rules. (This is also the main reason that spcasm is not published to crates.io.) The semver versioning applies to stability guarantees in the end-user applications, such as a minor version bump when new options and assembler directives are introduced, and a major version bump when incompatible changes to assembler syntax are introduced. Since the main purpose of the spcasm library is the use within this repository, vast changes may happen without prior warning and without a new release. If you plan to use spcasm as a library, please pin the dependency to a specific commit or version, and prepare to rework a bunch of your spcasm API usage when you do upgrade.
spcasm’s APIs are fairly stable, but since it has not been designed carefully for usability in other projects, there may be internals exposed that can change in violation of semver guarantees. High-level APIs, such as the ones that return an assembled ROM from given assembler source code, are expected to stay relatively stable. The semver versioning strongly applies to stability guarantees in the end-user applications, such as a minor version bump when new options and assembler directives are introduced, and a major version bump when incompatible changes to assembler syntax are introduced. If you plan to use spcasm as a library, please pin the dependency to a specific commit or version, and prepare to rework a bunch of your spcasm API usage when you do upgrade.

PRs and issues changing the public API may be accepted if the maintenance effort is not significant. In general, exposing more internal APIs is not a problem, but the lower-level APIs are even more in flux than higher-level ones.

spcfile provides strong semver guarantees, as it is designed specifically as a reusable library.

0 comments on commit c31afc9

Please sign in to comment.