Skip to content

Commit 53e5150

Browse files
xxuejiexxuejie
committed
Add README
1 parent ad3fe8d commit 53e5150

File tree

1 file changed

+157
-0
lines changed

1 file changed

+157
-0
lines changed

‎README.md

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,160 @@
11
# ckb-script-templates
22

33
This repository keeps a series of CKB script templates that can be inflated via [cargo-generate](https://github.com/cargo-generate/cargo-generate). Those templates enable a native development flow on mainstream Linux, macOS and Windows machines using stock version of latest stable Rust & clang C compiler.
4+
5+
## Usage
6+
7+
### Dependencies
8+
9+
The following dependencies are required for the templates:
10+
11+
* `git`, `make`, `sed`, `bash`, `sha256sum` and others Unix utilities. Refer to the documentation for your operating systems for how to install them. Chances are your system might already have them.
12+
* `Rust`: latest stable Rust installed via [rustup](https://rustup.rs/) should work. Make sure you have `riscv64` target installed via: `rustup target add riscv64imac-unknown-none-elf`
13+
* `Clang`: make sure you have clang 16+ installed, sample installtion steps for selected platforms are:
14+
+ Debian / Ubuntu: `wget https://apt.llvm.org/llvm.sh && chmod +x llvm.sh && sudo ./llvm.sh 16 && rm llvm.sh`
15+
+ Fedora 39+: `sudo dnf -y install clang`
16+
+ Archlinux: `sudo pacman --noconfirm -Syu clang`
17+
+ macOS: `brew install llvm@16`
18+
+ Windows(with [Scoop](scoop install llvm yasm)): `scoop install llvm yasm`
19+
* `cargo-generate`: You can install this via `cargo install cargo-generate`, or follow the steps [here](https://cargo-generate.github.io/cargo-generate/installation.html)
20+
21+
### Creating workspace
22+
23+
To generate a workspace template, use the following command:
24+
25+
```
26+
$ cargo generate gh:xxuejie/ckb-script-templates workspace
27+
⚠️ Favorite `gh:xxuejie/ckb-script-templates` not found in config, using it as a git repository: https://github.com/xxuejie/ckb-script-templates.git
28+
🤷 Project Name: my-first-contract-workspace
29+
🔧 Destination: /tmp/my-first-contract-workspace ...
30+
🔧 project-name: my-first-contract-workspace ...
31+
🔧 Generating template ...
32+
🔧 Moving generated files into: `/tmp/my-first-contract-workspace`...
33+
🔧 Initializing a fresh Git repository
34+
✨ Done! New project created /tmp/my-first-contract-workspace
35+
```
36+
37+
Or you can manually specify the name and skip the prompt:
38+
39+
```
40+
$ cargo generate gh:xxuejie/ckb-script-templates workspace --name my-first-contract-workspace
41+
⚠️ Favorite `gh:xxuejie/ckb-script-templates` not found in config, using it as a git repository: https://github.com/xxuejie/ckb-script-templates.git
42+
🔧 Destination: /tmp/my-first-contract-workspace ...
43+
🔧 project-name: my-first-contract-workspace ...
44+
🔧 Generating template ...
45+
🔧 Moving generated files into: `/tmp/my-first-contract-workspace`...
46+
🔧 Initializing a fresh Git repository
47+
✨ Done! New project created /tmp/my-first-contract-workspace
48+
```
49+
50+
This is probably the only longer command you will deal with when using the templates repository. You can save them as an alias in your shell:
51+
52+
```
53+
$ alias create-ckb-scripts="cargo generate gh:xxuejie/ckb-script-templates workspace"
54+
$ create-ckb-scripts
55+
⚠️ Favorite `gh:xxuejie/ckb-script-templates` not found in config, using it as a git repository: https://github.com/xxuejie/ckb-script-templates.git
56+
🤷 Project Name: my-first-contract-workspace
57+
🔧 Destination: /tmp/my-first-contract-workspace ...
58+
🔧 project-name: my-first-contract-workspace ...
59+
🔧 Generating template ...
60+
🔧 Moving generated files into: `/tmp/my-first-contract-workspace`...
61+
🔧 Initializing a fresh Git repository
62+
✨ Done! New project created /tmp/my-first-contract-workspace
63+
```
64+
65+
### Working in the workspace
66+
67+
First, navigate to the workspace directory you just created:
68+
69+
```
70+
$ cd my-first-contract-workspace
71+
```
72+
73+
First thing you can notice, is that we have created a standard Rust workspace project:
74+
75+
```
76+
$ tree .
77+
.
78+
├── Cargo.toml
79+
├── Makefile
80+
├── scripts
81+
│   └── find_clang
82+
└── tests
83+
├── Cargo.toml
84+
└── src
85+
├── lib.rs
86+
└── tests.rs
87+
88+
4 directories, 6 files
89+
```
90+
91+
The only exception here, is that a `Makefile`, together with a `scripts` folder has been created to simplify contract building.
92+
93+
We can use `make generate` to create our first contract:
94+
95+
```
96+
$ make generate
97+
🤷 Project Name: first-contract
98+
🔧 Destination: /tmp/my-first-contract-workspace/contracts/first-contract ...
99+
🔧 project-name: first-contract ...
100+
🔧 Generating template ...
101+
🔧 Moving generated files into: `/tmp/my-first-contract-workspace/contracts/first-contract`...
102+
🔧 Initializing a fresh Git repository
103+
✨ Done! New project created /tmp/my-first-contract-workspace/contracts/first-contract
104+
Please update workspace-level Cargo.toml so members include the newly created crate!
105+
```
106+
107+
As the log line hints, after creating the contract, we will need to manually update `Cargo.toml` file to contain the newly created contract crate. When you finished editing, `Cargo.toml` file should look like following:
108+
109+
```
110+
$ cat Cargo.toml
111+
[workspace]
112+
resolver = "2"
113+
114+
members = [
115+
# Please don't remove the following line, we use it to automatically
116+
# detect insertion point for newly generated crates.
117+
# @@INSERTION_POINT@@
118+
"contracts/first-contract",
119+
"tests",
120+
]
121+
122+
[profile.release]
123+
overflow-checks = true
124+
strip = true
125+
codegen-units = 1
126+
```
127+
128+
You can also supply the contract create name when executing the make task:
129+
130+
```
131+
$ make generate CRATE=second-contract
132+
🔧 Destination: /tmp/my-first-contract-workspace/contracts/second-contract ...
133+
🔧 project-name: second-contract ...
134+
🔧 Generating template ...
135+
🔧 Moving generated files into: `/tmp/my-first-contract-workspace/contracts/second-contract`...
136+
🔧 Initializing a fresh Git repository
137+
✨ Done! New project created /tmp/my-first-contract-workspace/contracts/second-contract
138+
```
139+
140+
Note that when you supply the contract crate name, our `Makefile` will be smart enough to automatically insert the crate in to `Cargo.toml` file, so you don't have to edit it manually.
141+
142+
Now you can build the contracts(or adjust parameters):
143+
144+
```
145+
$ make build
146+
$ make build MODE=debug # for debug build
147+
$ make build CUSTOM_RUSTFLAGS="" # release build without debug assertions
148+
$ make build CARGO_ARGS="--verbose" # release build with `--verbose` attached to cargo command, you can use other arguments accepted by cargo
149+
$ make build CONTRACT=second-contract # build a single contract
150+
$ make build CLEAN_BUILD_DIR_FIRST=false # keep old untouched binaries
151+
$ make build CLANG=clang-17 # use a specific clang version to build C code
152+
```
153+
154+
We have prepared a `tests` crate where you can also add contract tests. If you want to run the tests, run the following command:
155+
156+
```
157+
make test
158+
```
159+
160+
The templates provided here, use the same conventions as `ckb-native-build-sample` project, so feel free to refer to the more detailed [usage](https://github.com/xxuejie/ckb-native-build-sample?tab=readme-ov-file#usage) doc in the sample project.

0 commit comments

Comments
 (0)