Skip to content

Commit 8e6fd22

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 b68e6e7 commit 8e6fd22

File tree

1 file changed

+195
-74
lines changed

1 file changed

+195
-74
lines changed

‎README.md‎

Lines changed: 195 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -43,98 +43,219 @@ Or install the complete boost library with
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+
├── deserialize_offer/
149+
├── descriptor_parse/
150+
├── miniscript_parse/
151+
├── script_asm/
152+
├── deserialize_invoice/
153+
├── address_parse/
154+
└── psbt_parse/
155+
```
156+
- 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`.
157+
158+
## Manual Method
159+
160+
If you prefer, you can still build the modules manually. Below are the steps for each module:
161+
162+
### Bitcoin modules:
163+
164+
- ### rust-bitcoin
165+
166+
```bash
167+
cd modules/rustbitcoin
168+
make cargo && make
169+
export CXXFLAGS="$CXXFLAGS -DRUST_BITCOIN"
170+
```
46171
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
58-
59-
```bash
60-
cd modules/rustminiscript
61-
make cargo && make
62-
export CXXFLAGS="$CXXFLAGS -DRUST_MINISCRIPT"
63-
```
64-
65-
### btcd
172+
- ### rust-miniscript
66173
67-
```bash
68-
cd modules/btcd
69-
make
70-
export CXXFLAGS="$CXXFLAGS -DBTCD"
71-
```
174+
```bash
175+
cd modules/rustminiscript
176+
make cargo && make
177+
export CXXFLAGS="$CXXFLAGS -DRUST_MINISCRIPT"
178+
```
72179
73-
### embit
180+
- ### btcd
74181
75-
To run the fuzzer with `embit` module, you need to install the `embit` library.
182+
```bash
183+
cd modules/btcd
184+
make
185+
export CXXFLAGS="$CXXFLAGS -DBTCD"
186+
```
76187
77-
To install the `embit` library, you can use the following command:
78-
```bash
79-
cd modules/embit
80-
pip install -r embit_lib/requirements.txt
81-
```
188+
- ### embit
82189
83-
```bash
84-
cd modules/embit
85-
make
86-
export CXXFLAGS="$CXXFLAGS -DEMBIT"
87-
```
190+
To run the fuzzer with `embit` module, you need to install the `embit` library.
88191
89-
### Bitcoin Core
192+
To install the `embit` library, you can use the following command:
193+
```bash
194+
cd modules/embit
195+
pip install -r /requirements.txt
196+
```
90197
91-
```bash
92-
cd modules/bitcoin
93-
make
94-
export CXXFLAGS="$CXXFLAGS -DBITCOIN_CORE"
95-
```
198+
```bash
199+
cd modules/embit
200+
make
201+
export CXXFLAGS="$CXXFLAGS -DEMBIT"
202+
```
96203
97-
## Lightning modules:
204+
- ### Bitcoin Core
98205
99-
### LDK
206+
```bash
207+
cd modules/bitcoin
208+
make
209+
export CXXFLAGS="$CXXFLAGS -DBITCOIN_CORE"
210+
export BOOST_LIB_DIR="path/to/boost/"
211+
```
100212
101-
```bash
102-
cd modules/ldk
103-
make cargo && make
104-
export CXXFLAGS="$CXXFLAGS -DLDK"
105-
```
213+
### Lightning modules:
106214
107-
### lnd
215+
- ### LDK
108216
109-
```bash
110-
cd modules/lnd
111-
make
112-
export CXXFLAGS="$CXXFLAGS -DLND"
113-
```
217+
```bash
218+
cd modules/ldk
219+
make cargo && make
220+
export CXXFLAGS="$CXXFLAGS -DLDK"
221+
```
114222
115-
### NLightning
223+
- ### LND
116224
117-
```bash
118-
cd modules/nlightning
119-
make
120-
export CXXFLAGS="$CXXFLAGS -DNLIGHTNING"
121-
```
225+
```bash
226+
cd modules/lnd
227+
make
228+
export CXXFLAGS="$CXXFLAGS -DLND"
229+
```
122230
123-
### C-lightning
231+
- ### NLightning
124232
125-
```bash
126-
pip install mako
127-
git submodule update --init --recursive external/lightning
128-
cd modules/clightning
129-
make
130-
export CXXFLAGS="$CXXFLAGS -DCLIGHTNING"
131-
```
233+
```bash
234+
cd modules/nlightning
235+
make
236+
export CXXFLAGS="$CXXFLAGS -DNLIGHTNING"
237+
```
238+
- ### C-lightning
239+
240+
```bash
241+
pip install mako
242+
git submodule update --init --recursive external/lightning
243+
cd modules/clightning
244+
make
245+
export CXXFLAGS="$CXXFLAGS -DCLIGHTNING"
246+
```
132247
133-
Once the modules are compiled, you can compile bitcoinfuzz and execute it:
134-
```bash
135-
make
136-
FUZZ=target_name ./bitcoinfuzz
137-
```
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+
```
138259
139260
-------------------------------------------
140261
### Bugs/inconsistences/mismatches found by Bitcoinfuzz

0 commit comments

Comments
 (0)