gaspersic/solana
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Add doc content and feedback (#13563)

Browse Source
This commit is contained in:
Jack May
2020-11-13 10:18:04 -08:00
committed by GitHub
parent 01a4889b53
commit 887b0e4b72
23 changed files with 754 additions and 804 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/src/developing/deployed-programs/debugging.md
View File

@@ -9,15 +9,8 @@ that will allow RPC clients to interact with their program.
## Running unit tests
TODO
## Running on a Local Cluster
TODO
## Transaction Simulation
TODO
- [Testing with Rust](developing-rust.md#how-to-test)
- [Testing with C](developing-c.md#how-to-test)
## Logging
@@ -92,7 +85,7 @@ operations they wish to profile.
program](developing-c.md#compute-budget)
See [compute
budget](developing/programming-model/../../../programming-model/compute-budget.md)
budget](developing/programming-model/../../../programming-model/runtime.md/#compute-budget)
for more information.
## ELF Dump

14
docs/src/developing/deployed-programs/developing-c.md
View File

@@ -178,7 +178,7 @@ to log a message containing the remaining number of compute units the program
may consume before execution is halted
See [compute
budget](developing/programming-model/../../../programming-model/compute-budget.md)
budget](developing/programming-model/../../../programming-model/runtime.md/#compute-budget)
for more information.
## ELF Dump
@@ -200,14 +200,4 @@ $ make dump_<program name>
## Examples
TODO
### Logging
### Transferring Lamports
### Writing Account Data
### Custom Heap
### Cross-program Invocations
The [Solana Program Library github](https://github.com/solana-labs/solana-program-library/tree/master/examples/c) repo contains a collection of C examples

103
docs/src/developing/deployed-programs/developing-rust.md
View File

@@ -28,10 +28,11 @@ features = []
Solana Rust programs may depend directly on each other in order to gain access
to instruction helpers when making [cross-program
invocations](developing/../../programming-model/cpi.md). When doing so it's
important to not pull in the dependent program's entrypoint symbols because they
may conflict with the program's own. To avoid this ,programs should define an
`exclude_entrypoint` feature in `Cargo.toml`j and use to exclude the entrypoint.
invocations](developing/../../programming-model/calling-between-programs.md#cross-program-invocations).
When doing so it's important to not pull in the dependent program's entrypoint
symbols because they may conflict with the program's own. To avoid this
,programs should define an `exclude_entrypoint` feature in `Cargo.toml`j and use
to exclude the entrypoint.
- [Define the
feature](https://github.com/solana-labs/solana-program-library/blob/a5babd6cbea0d3f29d8c57d2ecbbd2a2bd59c8a9/token/program/Cargo.toml#L12)
@@ -48,29 +49,19 @@ using the `exclude_entrypoint` feature.
At a minimum, Solana Rust programs must pull in the
[solana-program](https://crates.io/crates/solana-program) crate.
Programs are constrained to run deterministically, so random numbers are not
available. Sometimes a program may depend on a crate that depends itself on
`rand` even if the program does not use any of the random number functionality.
If a program depends on `rand`, the compilation will fail because there is no
`get-random` support for Solana. The error will typically look like this:
Solana BPF programs have some [restrictions](#Restrictions) that may prevent the
inclusion of some crates as dependencies or require special handling.
```
error: target is not supported, for more information see: https://docs.rs/getrandom/#unsupported-targets
--> /Users/jack/.cargo/registry/src/github.com-1ecc6299db9ec823/getrandom-0.1.14/src/lib.rs:257:9
|
257 | / compile_error!("\
258 | | target is not supported, for more information see: \
259 | | https://docs.rs/getrandom/#unsupported-targets\
260 | | ");
| |___________^
```
To work around this dependency issue, add the following dependency to the
program's `Cargo.toml`:
```
getrandom = { version = "0.1.14", features = ["dummy"] }
```
For example:
- Crates that require the architecture be a subset of the ones supported by the
official toolchain. There is no workaround for this unless that crate is
forked and BPF added to that those architecture checks.
- Crates may depend on `rand` which is not supported in Solana's deterministic
program environment. To include a `rand` dependent crate refer to [Depending
on Rand](#depending-on-rand).
- Crates may overflow the stack even if the stack overflowing code isn't
included in the program itself. For more information refer to
[Stack](overview.md#stack).
## How to Build
@@ -96,7 +87,19 @@ $ cargo build-bpf
## How to Test
TODO
Solana programs can be unit tested via the traditional `cargo test` mechanism by
exercising program functions directly.
To help facilitate testing in an environment that more closely matches a live
cluster, developers can use the
[`program-test`](https://crates.io/crates/solana-program-test) crate. The
`program-test` crate starts up a local instance of the runtime and allows tests
to send multiple transactions while keeping state for the duration of the test.
For more information the [test in sysvar
example](https://github.com/solana-labs/solana-program-library/blob/master/examples/rust/sysvar/tests/functional.rs)
shows how an instruction containing syavar account is sent and processed by the
program.
## Program Entrypoint
@@ -240,9 +243,35 @@ single-threaded environment, and must be deterministic:
should be used instead.
- The runtime enforces a limit on the number of instructions a program can
execute during the processing of one instruction. See [computation
budget](developing/programming-model/compute-budget.md) for more
budget](developing/programming-model/runtime.md#compute-budget) for more
information.
## Depending on Rand
Programs are constrained to run deterministically, so random numbers are not
available. Sometimes a program may depend on a crate that depends itself on
`rand` even if the program does not use any of the random number functionality.
If a program depends on `rand`, the compilation will fail because there is no
`get-random` support for Solana. The error will typically look like this:
```
error: target is not supported, for more information see: https://docs.rs/getrandom/#unsupported-targets
--> /Users/jack/.cargo/registry/src/github.com-1ecc6299db9ec823/getrandom-0.1.14/src/lib.rs:257:9
|
257 | / compile_error!("\
258 | | target is not supported, for more information see: \
259 | | https://docs.rs/getrandom/#unsupported-targets\
260 | | ");
| |___________^
```
To work around this dependency issue, add the following dependency to the
program's `Cargo.toml`:
```
getrandom = { version = "0.1.14", features = ["dummy"] }
```
## Logging
Rust's `println!` macro is computationally expensive and not supported. Instead
@@ -337,7 +366,7 @@ to log a message containing the remaining number of compute units the program
may consume before execution is halted
See [compute
budget](developing/programming-model/../../../programming-model/compute-budget.md)
budget](developing/programming-model/../../../programming-model/runtime.md#compute-budget)
for more information.
## ELF Dump
@@ -359,16 +388,6 @@ $ cargo build-bpf --dump
## Examples
TODO
### Logging
### Transferring Lamports
### Writing Account Data
### Using a Sysvar
### Custom Heap
### Cross-program Invocations
The [Solana Program Library
github](https://github.com/solana-labs/solana-program-library/tree/master/examples/rust)
repo contains a collection of Rust examples.

12
docs/src/developing/deployed-programs/examples.md
View File

@@ -2,6 +2,7 @@
title: "Examples"
---
## Helloworld
Hello World is a project that demonstrates how to use the Solana Javascript API
@@ -13,7 +14,7 @@ The project comprises of:
- A client that can send a "hello" to an account and get back the number of
times "hello" has been sent
## Build and run Hello World program
### Build and Run
First fetch the latest version of the example code:
@@ -30,7 +31,7 @@ Next, follow the steps in the git repository's
[Break](https://break.solana.com/) is a React app that gives users a visceral
feeling for just how fast and high-performance the Solana network really is. Can
you _break_ the Solana blockchain? During a 15 second playthough, each click of
you _break_ the Solana blockchain? During a 15 second play-though, each click of
a button or keystroke sends a new transaction to the cluster. Smash the keyboard
as fast as you can and watch your transactions get finalized in real time while
the network takes it all in stride!
@@ -43,7 +44,7 @@ transfer the tokens.
[Click here to play Break](https://break.solana.com/)
## Build and run Break locally
### Build and Run
First fetch the latest version of the example code:
@@ -54,3 +55,8 @@ $ cd break
Next, follow the steps in the git repository's
[README](https://github.com/solana-labs/break/blob/master/README.md).
## Language Specific
- [Rust](developing-rust.md#examples)
- [C](developing-c.md#examples)

8
docs/src/developing/deployed-programs/faq.md
View File

@@ -15,7 +15,7 @@ This error means that that cross-program invocation exceeded the allowed
invocation call depth.
See [cross-program invocation Call
Depth](developing/programming-model/cpi.md#call-depth)
Depth](developing/programming-model/calling-between-programs.md#call-depth)
## `CallDepthExceeded` error
@@ -26,7 +26,7 @@ See [call depth](overview.md#call-depth)
## Computational constraints
See [computational
constraints](developing/programming-model/compute-budget.md)
constraints](developing/programming-model/runtime.md#compute-budget)
## Float Rust types
@@ -64,9 +64,9 @@ an account is expected to be signed but is not.
An implementation of a program might also cause this error when performing a
cross-program invocation that requires a signed program address, but the passed
signer seeds passed to [`invoke_signed`](developing/programming-model/cpi.md)
signer seeds passed to [`invoke_signed`](developing/programming-model/calling-between-programs.md)
don't match the signer seeds used to create the program address
[`create_program_address`](developing/programming-model/program-derived-addresses.md).
[`create_program_address`](developing/programming-model/calling-between-programs.md#program-derived-addresses).
## `rand` Rust dependency causes compilation failure