Skip to content

Commit e006ec2

Browse files
moisesPompiliomoisesPompilio
committed
doc: add build instructions for auto_build.sh and Docker
Added documentation to README.md detailing the usage of auto_build.sh for automated module compilation and cleaning. Included instructions for building and running the application using Docker and Docker Compose, with examples for environment variables and volume mounts.
1 parent ac3add1 commit e006ec2

File tree

1 file changed

+194
-74
lines changed

1 file changed

+194
-74
lines changed

‎README.md‎

Lines changed: 194 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -30,112 +30,232 @@ Note this project is a WIP and might be not stable.
3030
3131
### boost
3232
33-
To build the bitcoin core module the boost library is required. Minimum version
33+
To build the bitcoin core module the boost library is required. Minimum version
3434
3535
The module uses only libboost-filesystem and libboost-system modules. For ubuntu you can install with:
3636
3737
```
3838
sudo apt install libboost-filesystem-dev libboost-system-dev
3939
```
4040
41-
Or install the complete boost library with
41+
Or install the complete boost library with
4242
```
4343
sudo apt install libboost-all-dev
4444
```
4545
46+
# Build Options
47+
48+
You can build the modules in two ways: **manual** or **automatic**. The automatic method is provided by the `auto_build.sh` script, which simplifies the build and clean processes. Additionally, you can use **Docker** or **Docker Compose** to run the application without installing dependencies directly on your machine.
49+
50+
## Automatic Method: `auto_build.sh`
51+
52+
The `auto_build.sh` script allows you to automatically build the modules based on the flags defined in `CXXFLAGS`. It also provides options to clean the builds before compiling.
53+
54+
### How to use:
55+
56+
1. **Automatic Build**:
57+
- To automatically build the modules, define the flags in `CXXFLAGS` and run the script:
58+
```bash
59+
CXXFLAGS="-DLDK -DLND" ./auto_build.sh
60+
```
61+
This will automatically build the `LDK` and `LND` modules.
62+
63+
2. **Automatic Clean**:
64+
- The script supports three cleaning modes before building:
65+
- **Full Clean**: Cleans all modules before building the selected ones.
66+
```bash
67+
CLEAN_BUILD="FULL" CXXFLAGS="-DLDK -DLND" ./auto_build.sh
68+
```
69+
- **Clean**: Cleans only the modules that will be built based on `CXXFLAGS`.
70+
```bash
71+
CLEAN_BUILD="CLEAN" CXXFLAGS="-DLDK -DLND" ./auto_build.sh
72+
```
73+
- **Select Clean**: Cleans specific modules defined in `CLEAN_BUILD`, regardless of `CXXFLAGS`.
74+
```bash
75+
CLEAN_BUILD="-DLDK -DBTCD" CXXFLAGS="-DLDK -DLND" ./auto_build.sh
76+
```
77+
In this case, the script will run `make clean` for `LDK` and `BTCD`, but will only build the modules defined in `CXXFLAGS` (`LDK` and `LND`).
78+
79+
## Docker Method
80+
81+
If you prefer not to install dependencies directly on your machine, you can use Docker to run the application. This method simplifies deployment and ensures a consistent environment.
82+
83+
### Using the Dockerfile
84+
85+
1. **Build the Docker Image**:
86+
- Build the Docker image using the provided `docker`:
87+
```bash
88+
docker build -t bitcoinfuzz .
89+
```
90+
91+
2. **Run the Container**:
92+
- Run the container with the required `FUZZ` and `CXXFLAGS` environment variables:
93+
```bash
94+
docker run -e FUZZ=target_name -e CXXFLAGS="-DLDK -DLND ..." bitcoinfuzz
95+
```
96+
97+
3. **Optional Parameters**:
98+
- You can also pass optional parameters:
99+
- **`FUZZ_RUNS`**: Specify the number of fuzzing runs (e.g., 50):
100+
```bash
101+
docker run -e FUZZ=target_name -e CXXFLAGS="-DLDK -DLND ..." -e FUZZ_RUNS=50 bitcoinfuzz
102+
```
103+
- **`FUZZ_INPUT`**: Provide a specific corpus or crash file to test:
104+
```bash
105+
docker run -e FUZZ=target_name -e CXXFLAGS="-DLDK -DLND ..." -e FUZZ_INPUT=/path/to/input bitcoinfuzz
106+
```
107+
108+
4. **Accessing Generated Corpus**:
109+
- The generated corpus is saved in `/app/data` inside the container. To access it, you can mount a volume:
110+
```bash
111+
docker run -e FUZZ=target_name -e CXXFLAGS="-DLDK -DLND ..." -v $(pwd)/corpus:/app/data bitcoinfuzz
112+
```
113+
114+
### Using Docker Compose
115+
116+
The `docker-compose.yml` file simplifies running multiple fuzzing scenarios. Each scenario is preconfigured with the required modules and environment variables.
117+
118+
1. **Run All Scenarios**:
119+
- To run all scenarios, simply execute:
120+
```bash
121+
docker-compose up
122+
```
123+
124+
2. **Run a Specific Scenario**:
125+
- To run a specific scenario (e.g., `script`), use:
126+
```bash
127+
docker-compose up script
128+
```
129+
130+
3. **Optional Parameters**:
131+
- You can pass optional parameters like `FUZZ_RUNS` or `FUZZ_INPUT`:
132+
- Run with a specific number of fuzzing runs:
133+
```bash
134+
FUZZ_RUNS=50 docker-compose up script
135+
```
136+
- Run with a specific input file:
137+
```bash
138+
FUZZ_INPUT=/path/to/input docker-compose up script
139+
```
140+
141+
4. **Accessing Generated Corpus**:
142+
- The generated corpus for each scenario is saved in the `docker` directory at the same level as the `docker-compose.yml` file. Each scenario has its own subdirectory:
143+
```
144+
docker/
145+
├── script/
146+
├── deserialize_block/
147+
├── script_eval/
148+
├── descriptor_parse/
149+
├── miniscript_parse/
150+
├── script_asm/
151+
├── deserialize_invoice/
152+
├── address_parse/
153+
└── psbt_parse/
154+
```
155+
- To ensure the corpus is saved locally, the `docker-compose.yml` file maps the `/app/data` directory inside the container to the corresponding subdirectory in `docker`.
156+
157+
## Manual Method
158+
159+
If you prefer, you can still build the modules manually. Below are the steps for each module:
160+
161+
### Bitcoin modules:
162+
163+
- ### rust-bitcoin
164+
165+
```bash
166+
cd modules/rustbitcoin
167+
make cargo && make
168+
export CXXFLAGS="$CXXFLAGS -DRUST_BITCOIN"
169+
```
46170
47-
## Bitcoin modules:
48-
49-
### rust-bitcoin
50-
51-
```bash
52-
cd modules/rustbitcoin
53-
make cargo && make
54-
export CXXFLAGS="$CXXFLAGS -DRUST_BITCOIN"
55-
```
56-
57-
### rust-miniscript
171+
- ### rust-miniscript
58172
59-
```bash
60-
cd modules/rustminiscript
61-
make cargo && make
62-
export CXXFLAGS="$CXXFLAGS -DRUST_MINISCRIPT"
63-
```
173+
```bash
174+
cd modules/rustminiscript
175+
make cargo && make
176+
export CXXFLAGS="$CXXFLAGS -DRUST_MINISCRIPT"
177+
```
64178
65-
### mako
179+
- ### mako
66180
67-
For the `script_eval` target, we recommend to get Mako from https://github.com/brunoerg/mako/tree/bitcoinfuzz since there are some checks that should be skipped for better fuzzing.
181+
For the `script_eval` target, we recommend to get Mako from https://github.com/brunoerg/mako/tree/bitcoinfuzz since there are some checks that should be skipped for better fuzzing.
68182
69-
```bash
70-
cd modules/mako
71-
export MAKO_LIB_PATH="path/to/libmako.a"
72-
make
73-
```
183+
```bash
184+
cd modules/mako
185+
export MAKO_LIB_PATH="path/to/libmako.a"
186+
make
187+
```
74188
75-
### btcd
189+
- ### btcd
76190
77-
```bash
78-
cd modules/btcd
79-
make
80-
export CXXFLAGS="$CXXFLAGS -DBTCD"
81-
```
191+
```bash
192+
cd modules/btcd
193+
make
194+
export CXXFLAGS="$CXXFLAGS -DBTCD"
195+
```
82196
83-
### embit
197+
- ### embit
84198
85-
To run the fuzzer with `embit` module, you need to install the `embit` library.
199+
To run the fuzzer with `embit` module, you need to install the `embit` library.
86200
87-
To install the `embit` library, you can use the following command:
88-
```bash
89-
cd modules/embit
90-
pip install -r embit_lib/requirements.txt
91-
```
201+
To install the `embit` library, you can use the following command:
202+
```bash
203+
cd modules/embit
204+
pip install -r embit_lib/requirements.txt
205+
```
92206
93-
```bash
94-
cd modules/embit
95-
make
96-
export CXXFLAGS="$CXXFLAGS -DEMBIT"
97-
```
207+
```bash
208+
cd modules/embit
209+
make
210+
export CXXFLAGS="$CXXFLAGS -DEMBIT"
211+
```
98212
99-
### Bitcoin Core
213+
- ### Bitcoin Core
100214
101-
```bash
102-
cd modules/bitcoin
103-
make
104-
export CXXFLAGS="$CXXFLAGS -DBITCOIN_CORE"
105-
export BOOST_LIB_DIR="path/to/boost/"
106-
```
215+
```bash
216+
cd modules/bitcoin
217+
make
218+
export CXXFLAGS="$CXXFLAGS -DBITCOIN_CORE"
219+
export BOOST_LIB_DIR="path/to/boost/"
220+
```
107221
108-
## Lightning modules:
222+
### Lightning modules:
109223
110-
### LDK
224+
- ### LDK
111225
112-
```bash
113-
cd modules/ldk
114-
make cargo && make
115-
export CXXFLAGS="$CXXFLAGS -DLDK"
116-
```
226+
```bash
227+
cd modules/ldk
228+
make cargo && make
229+
export CXXFLAGS="$CXXFLAGS -DLDK"
230+
```
117231
118-
### lnd
232+
- ### LND
119233
120-
```bash
121-
cd modules/lnd
122-
make
123-
export CXXFLAGS="$CXXFLAGS -DLND"
124-
```
234+
```bash
235+
cd modules/lnd
236+
make
237+
export CXXFLAGS="$CXXFLAGS -DLND"
238+
```
125239
126-
### NLightning
240+
- ### NLightning
127241
128-
```bash
129-
cd modules/nlightning
130-
make
131-
export CXXFLAGS="$CXXFLAGS -DNLIGHTNING"
132-
```
242+
```bash
243+
cd modules/nlightning
244+
make
245+
export CXXFLAGS="$CXXFLAGS -DNLIGHTNING"
246+
```
133247
134-
Once the modules are compiled, you can compile bitcoinfuzz and execute it:
135-
```bash
136-
make
137-
FUZZ=target_name ./bitcoinfuzz
138-
```
248+
## Final Build and Execution
249+
Once the modules are compiled, you can compile `bitcoinfuzz` an execute it:
250+
- ### Automatic Method:
251+
```bash
252+
FUZZ=target_name ./bitcoinfuzz
253+
```
254+
- ### Manual Method:
255+
```bash
256+
make
257+
FUZZ=target_name ./bitcoinfuzz
258+
```
139259
140260
-------------------------------------------
141261
### Bugs/inconsistences/mismatches found by Bitcoinfuzz

0 commit comments

Comments
 (0)