|
| 1 | +# The VIBES Tool Suite |
| 2 | + |
| 3 | +A suite of tools for the VIBES project. |
| 4 | + |
| 5 | + |
| 6 | +## The Tools |
| 7 | + |
| 8 | +In progress. So far, the tools that are under development are these: |
| 9 | + |
| 10 | +* `vibes-parse` ([README.md](tools/vibes-parse)) - Takes a `patch.c` file (containing C code), and produces a `patch.bir` file (containing serialized BAP IR). |
| 11 | +* `vibes-opt` ([README.md](tools/vibes-opt)) - Takes a `patch.bir` file, and produces a `patch.bir.opt` file (containing optimized BAP IR). |
| 12 | + |
| 13 | + |
| 14 | +## Building/Installing everything |
| 15 | + |
| 16 | +To build and install the entire suite: |
| 17 | + |
| 18 | +``` |
| 19 | +make |
| 20 | +``` |
| 21 | + |
| 22 | +Check that all tools are installed: |
| 23 | + |
| 24 | +``` |
| 25 | +vibes-parse --help |
| 26 | +vibes-opt --help |
| 27 | +``` |
| 28 | + |
| 29 | +or: |
| 30 | + |
| 31 | +``` |
| 32 | +vibes-parse --version |
| 33 | +vibes-opt --version |
| 34 | +``` |
| 35 | + |
| 36 | +To just build the suite: |
| 37 | + |
| 38 | +``` |
| 39 | +make build |
| 40 | +``` |
| 41 | + |
| 42 | +To install the suite: |
| 43 | + |
| 44 | +``` |
| 45 | +make install |
| 46 | +``` |
| 47 | + |
| 48 | +To uninstall and clean: |
| 49 | + |
| 50 | +``` |
| 51 | +make uninstall |
| 52 | +make clean |
| 53 | +``` |
| 54 | + |
| 55 | + |
| 56 | +## Building/installing one tool |
| 57 | + |
| 58 | +To build, install, uninstall, or clean a single tool, use `make tool-name`, e.g.: |
| 59 | + |
| 60 | +``` |
| 61 | +make vibes-parse |
| 62 | +``` |
| 63 | + |
| 64 | +To build, install, uninstall, or clean the tool, append `.tool-name` to the `build`, `install`, `uninstall`, and `clean` targets. E.g., |
| 65 | + |
| 66 | +``` |
| 67 | +make build.vibes-parse |
| 68 | +make install.vibes-parse |
| 69 | +make uninstall.vibes-parse |
| 70 | +make clean.vibes-parse |
| 71 | +``` |
| 72 | + |
| 73 | + |
| 74 | +## Toy/sample CLI |
| 75 | + |
| 76 | +There is a toy/dummy command line tool that can be used a a playground or as a template for your own tool. |
| 77 | + |
| 78 | +It lives here: |
| 79 | + |
| 80 | +* [tools/vibes-playground](tools/vibes-playground) |
| 81 | + |
| 82 | +To use it, go to [tools/vibes-playground/bin/main.ml#L21](tools/vibes-playground/bin/main.ml#L21) and start modifying/playing. Then build/install: |
| 83 | + |
| 84 | +``` |
| 85 | +make vibes-playground |
| 86 | +``` |
| 87 | + |
| 88 | +And try it out from the command line: |
| 89 | + |
| 90 | +``` |
| 91 | +vibes-playground --help |
| 92 | +vibes-playground |
| 93 | +``` |
| 94 | + |
| 95 | + |
| 96 | +## Tool scaffolding |
| 97 | + |
| 98 | +The repo root of this tool suite currently lives at [VIBES-internal/experiments/vibes-tools](https://github.com/draperlaboratory/VIBES-internal/tree/main/experiments/vibes-tools). |
| 99 | + |
| 100 | +The tool suite is then contained in the [tools/](tools/) subdirectory, where each tool has its own folder, like this: |
| 101 | + |
| 102 | +``` |
| 103 | +|-- <repo root>/ |
| 104 | + | |
| 105 | + |-- "README.md" (top level README) |
| 106 | + |-- "Makefile" (top level makefile) |
| 107 | + |-- ... |
| 108 | + |-- "tools/" |
| 109 | + | |
| 110 | + |-- ... |
| 111 | + |-- "vibes-parse/" (folder containing the vibes-parse tool) |
| 112 | + |-- "vibes-opt/" (folder containing the vibes-opt tool) |
| 113 | + |-- "vibes-log/" (folder containing a shared logging library) |
| 114 | + |-- "vibes-error/" (folder containing a shared error handling library) |
| 115 | + |-- ... |
| 116 | +``` |
| 117 | + |
| 118 | +Some tools are command line tools. Other tools are just libraries that can be used by other tools. Each tool has a similar scaffolding. It's folder contains: |
| 119 | + |
| 120 | +* A `README.md` describing the tool/library and how to build/install it |
| 121 | +* A `Makefile` for building the tool |
| 122 | +* A possible `lib` folder, containing local library files just for this tool |
| 123 | +* A possible `bin` folder, containing files that define the CLI just for this tool |
| 124 | + |
| 125 | +For instance, consider a command line tool called `vibes-foo`. It would live in its own folder called `vibes-foo/`, which would look like this: |
| 126 | + |
| 127 | +``` |
| 128 | +|-- <repo root>/ |
| 129 | + | |
| 130 | + |-- ... |
| 131 | + |-- "tools/" |
| 132 | + | |
| 133 | + |-- "vibes-foo/" |
| 134 | + | |
| 135 | + |-- "README.md" |
| 136 | + |-- "Makefile" |
| 137 | + |-- "lib/" |
| 138 | + | | |
| 139 | + | |-- "dune" (defines "vibes_foo_lib", a non-public library) |
| 140 | + | |-- "runner.ml" (contains a "run" method, to run the library) |
| 141 | + | |-- "types.ml" (contains type definitions for this library) |
| 142 | + | |-- "module_a.ml" |
| 143 | + | |-- "module_b.ml" |
| 144 | + | |-- ... |
| 145 | + |-- "bin/" |
| 146 | + | |
| 147 | + |-- "dune" (defines a "main.exe" executable) |
| 148 | + |-- "main.ml" (defines the Cmdliner CLI) |
| 149 | +``` |
| 150 | + |
| 151 | +Note that a non-public library is defined in the `lib/` folder. Regarding this `lib/` folder, note the following: |
| 152 | + |
| 153 | +* These 'lib/' files make up a library that is not public (no `.opam` file). It is not meant to be installed separately as an opam package. Rather, it is just a library to be used locally by the tool `vibes-foo`. |
| 154 | +* Although this local library does not need an `.opam` file, it does need a `dune` file. In that file, we name this local library `vibes_foo_lib`. The convention is to append `_lib` to the end of the tool name (hence, if the tool were called `vibes-bar`, then this library would be named `vibes_bar_lib`). |
| 155 | +* If the library can be "run" (as an application), then there should be a `Runner` module that contains a `run` function, so that a CLI frontend can directly "run" it by calling `Vibes_foo_lib.Runner.run`. |
| 156 | +* If the library uses any shared types, they should be declared in a `types.ml` module. |
| 157 | + |
| 158 | +Note that a `main.exe` executable is defined in the `bin/` folder. Regarding this `bin/` folder, note the following: |
| 159 | + |
| 160 | +* The `bin/` folder is for housing the binary executable `vibes-foo` (a command line tool). |
| 161 | +* The CLI should be defined (using `Cmdliner`) in a file called `main.ml`. |
| 162 | +* There should be a `dune` file, defining the executable as `main.exe`. |
| 163 | +* The `install` target in `<repo root>/tools/vibes-foo/Makefile` should take the built executable `main.exe`, and install it on your system at `${OPAM_SWITCH_PREFIX}/bin`, under the name `vibes-foo`. That way, once the user has installed the tool, they can find the tool by the name `vibes-foo`. |
| 164 | + |
| 165 | +If a tool is just a library meant to be used by other tools (hence it has no CLI frontend of its own), then it should not have a `bin/` folder. Conversely, if a tool is just a CLI frontend that relies entirely on other shared libraries, then it need not have a `lib/` folder. |
| 166 | + |
| 167 | +Other conventions: |
| 168 | + |
| 169 | +* Functionality shared by more than one tool should be moved into its own library. |
| 170 | +* Other tools can import shared libraries by listing them in the `libraries` stanza of their local `dune` files. |
| 171 | +* The `<repo root>/tools/vibes-log` library provides a common logger that other tools should use for logging. Messages can be sent from any application by invoking the `Vibes_log.Stream.send` function. |
| 172 | +* The `<repo root>/tools/vibes-error` library provides a common error type that other tools should use. The type is extensible, so every tool can add its own custom errors and custom error printers. Such custom errors and printers should be declared in the tools `lib/types.ml` module. In general, any public function from a library should return a `(_, Vibes_error.Std.t) result` type. That way, consumers (i.e., CLI frontends) can automatically handle errors and print them out for the user with an appropriate exit code. |
| 173 | +* The `<repo root>/tools/vibes-common-cli-options` library provides various command line options that multiple tools share. For instance, it provides verbosity options that other tools can import into their own CLI. |
| 174 | +* The `<repo root>/tools/vibes-constants` library provides constant values that other applications can use. For instance, it specifies the version numbers for the various command line tools. Those CLIs simply import their version number from this `vibes-constants` library. |
| 175 | + |
| 176 | +When in doubt about a convention, look at some of the tools (e.g., `vibes-parse` or `vibes-opt`) and copy what you see there. |
0 commit comments