2020-05-29 15:00:47 -07:00
|
|
|
[![Build status][travis-image]][travis-url]
|
|
|
|
|
2020-07-28 11:00:37 -07:00
|
|
|
[travis-image]:
|
|
|
|
https://travis-ci.org/solana-labs/solana-program-library.svg?branch=master
|
2020-05-29 15:00:47 -07:00
|
|
|
[travis-url]: https://travis-ci.org/solana-labs/solana-program-library
|
|
|
|
|
2020-05-29 12:41:23 -07:00
|
|
|
# Solana Program Library
|
|
|
|
|
2020-05-31 08:52:00 -07:00
|
|
|
The Solana Program Library (SPL) is a collection of on-chain programs targeting
|
2020-07-28 11:00:37 -07:00
|
|
|
the [Sealevel parallel
|
|
|
|
runtime](https://medium.com/solana-labs/sealevel-parallel-processing-thousands-of-smart-contracts-d814b378192).
|
|
|
|
These programs are tested against Solana's implementation of Sealevel,
|
|
|
|
solana-runtime, and deployed to its mainnet. As others implement Sealevel, we
|
|
|
|
will graciously accept patches to ensure the programs here are portable across
|
|
|
|
all implementations.
|
|
|
|
|
|
|
|
Full documentation is available at https://spl.solana.com
|
2020-06-05 11:34:17 -07:00
|
|
|
|
2020-10-22 21:44:27 -07:00
|
|
|
## Development
|
2020-06-05 11:34:17 -07:00
|
|
|
|
2020-10-22 21:44:27 -07:00
|
|
|
### Environment Setup
|
2020-06-05 11:34:17 -07:00
|
|
|
|
2020-10-22 21:44:27 -07:00
|
|
|
1. Install the latest Rust stable from https://rustup.rs/
|
2020-11-12 09:19:39 -08:00
|
|
|
2. Install Solana v1.4.7 or later from https://docs.solana.com/cli/install-solana-cli-tools
|
2020-06-05 11:34:17 -07:00
|
|
|
|
2020-10-22 21:44:27 -07:00
|
|
|
### Build
|
|
|
|
|
|
|
|
The normal cargo build is available for building programs against your host machine:
|
|
|
|
```
|
|
|
|
$ cargo build
|
2020-06-05 11:34:17 -07:00
|
|
|
```
|
|
|
|
|
2020-10-22 21:44:27 -07:00
|
|
|
To build a specific program, such as SPL Token, for the Solana BPF target:
|
|
|
|
```
|
|
|
|
$ cd token/program
|
|
|
|
$ cargo build-bpf
|
2020-06-05 11:34:17 -07:00
|
|
|
```
|
|
|
|
|
2020-10-22 21:44:27 -07:00
|
|
|
### Test
|
2020-06-05 11:34:17 -07:00
|
|
|
|
2020-10-22 21:44:27 -07:00
|
|
|
Unit tests contained within all projects can be run with:
|
2020-06-05 11:34:17 -07:00
|
|
|
```bash
|
2020-11-06 09:31:24 -08:00
|
|
|
$ cargo test # <-- runs host-based tests
|
|
|
|
$ cargo test-bpf # <-- runs BPF program tests
|
2020-06-05 11:34:17 -07:00
|
|
|
```
|
|
|
|
|
2020-10-22 21:44:27 -07:00
|
|
|
To run a specific program's tests, such as SPL Token:
|
|
|
|
```
|
|
|
|
$ cd token/program
|
2020-11-06 09:31:24 -08:00
|
|
|
$ cargo test # <-- runs host-based tests
|
|
|
|
$ cargo test-bpf # <-- runs BPF program tests
|
2020-06-05 11:34:17 -07:00
|
|
|
```
|
|
|
|
|
2020-10-22 21:44:27 -07:00
|
|
|
Integration testing may be performed via the per-project .js bindings. See the
|
2020-07-28 11:00:37 -07:00
|
|
|
[token program's js project](token/js) for an example.
|
2020-06-24 10:56:25 -07:00
|
|
|
|
2020-10-22 21:44:27 -07:00
|
|
|
### Clippy
|
2020-06-05 11:34:17 -07:00
|
|
|
```bash
|
2020-10-22 21:44:27 -07:00
|
|
|
$ cargo clippy
|
2020-06-05 11:34:17 -07:00
|
|
|
```
|
|
|
|
|
2020-10-22 21:44:27 -07:00
|
|
|
### Coverage
|
|
|
|
```bash
|
2020-11-06 09:31:24 -08:00
|
|
|
$ ./coverage.sh # Please help! Coverage build currently fails on MacOS due to an XCode `grcov` mismatch...
|
2020-06-05 11:34:17 -07:00
|
|
|
```
|
2020-07-29 10:26:04 -07:00
|
|
|
|
|
|
|
|
2020-10-22 21:44:27 -07:00
|
|
|
## Release Process
|
2020-07-29 10:26:04 -07:00
|
|
|
SPL programs are currently tagged and released manually. Each program is
|
|
|
|
versioned independently of the others, with all new development occurring on
|
|
|
|
master. Once a program is tested and deemed ready for release:
|
|
|
|
|
|
|
|
### Bump Version
|
|
|
|
|
|
|
|
* Increment the version number in the program's Cargo.toml
|
|
|
|
* Generate a new program ID and replace in `<program>/program-id.md` and `<program>/src/lib.rs`
|
2020-10-22 21:44:27 -07:00
|
|
|
* Run `cargo build <program>` to update relevant C bindings. (Note the
|
|
|
|
location of the generated `spl_<program>.so` for attaching to the Github
|
|
|
|
release.)
|
2020-07-29 10:26:04 -07:00
|
|
|
* Open a PR with these version changes and merge after passing CI.
|
|
|
|
|
|
|
|
### Create Github tag
|
|
|
|
|
|
|
|
Program tags are of the form `<program>-vX.Y.Z`.
|
|
|
|
Create the new tag at the version-bump commit and push to the
|
|
|
|
solana-program-library repository, eg:
|
|
|
|
|
|
|
|
```
|
|
|
|
$ git tag token-v1.0.0 b24bfe7
|
|
|
|
$ git push upstream --tags
|
|
|
|
```
|
|
|
|
|
|
|
|
### Publish Github release
|
|
|
|
|
|
|
|
* Go to [GitHub Releases UI](https://github.com/solana-labs/solana-program-library/releases)
|
|
|
|
* Click "Draft new release", and enter the new tag in the "Tag version" box.
|
|
|
|
* Title the release "SPL <Program> vX.Y.Z", complete the description, and attach the `spl_<program>.so` binary
|
|
|
|
* Click "Publish release"
|
|
|
|
|
|
|
|
### Publish to Crates.io
|
|
|
|
|
|
|
|
Navigate to the program directory and run `cargo package`
|
|
|
|
to test the build. Then run `cargo publish`. (Currently, programs with generated
|
|
|
|
C bindings fail the final step of verification due to the location of the
|
|
|
|
generated file. Once you are certain the crate is ready, run `cargo publish --no-verify`
|
|
|
|
to bypass this error.)
|