diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 89 |
1 files changed, 45 insertions, 44 deletions
| @@ -13,40 +13,50 @@ of pruning tables that were developed independently. | |||
| 13 | 13 | ||
| 14 | ## Building | 14 | ## Building |
| 15 | 15 | ||
| 16 | First run the configuration script to detect the system configuration. | 16 | This project currently supports only POSIX systems (Linux, MacOS, BSD...). |
| 17 | This is going to select a C compiler and architecture-specific optimizations. | 17 | If you want to build on Windows you can do so via |
| 18 | [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). Note that | ||
| 19 | the resulting executable will not be a native Windows executable. | ||
| 20 | Windows as a build target will be available in the future. | ||
| 21 | |||
| 22 | To build nissy simply run | ||
| 18 | 23 | ||
| 19 | ``` | 24 | ``` |
| 20 | $ ./configure.sh | 25 | $ ./build |
| 21 | ``` | 26 | ``` |
| 22 | 27 | ||
| 23 | These settings can be overridden, for example: | 28 | For a list of options and targets for the build system run `./build help`. |
| 29 | Some compiler settings can be overridden using environment variables, | ||
| 30 | as explained in the comments at the beginning of the build script. For | ||
| 31 | example, the command: | ||
| 24 | 32 | ||
| 25 | ``` | 33 | ``` |
| 26 | $ THREADS=3 CC=gcc ./configure.sh # Use 3 threads and compile with gcc | 34 | $ export NISSY_BUILD_THREADS=3 |
| 35 | $ CC=gcc ./build | ||
| 27 | ``` | 36 | ``` |
| 28 | 37 | ||
| 29 | All the configuration-time options are described in the `configure.sh` script. | 38 | is going to configure `nissy` to use at most 3 threads, and build it with |
| 39 | `gcc`. Se the comments in `./build` for more details. | ||
| 40 | |||
| 41 | ## Running tests | ||
| 30 | 42 | ||
| 31 | Once the configuration is done, you can build with make | 43 | This project includes a suite of "unit" test. You can run them with: |
| 32 | 44 | ||
| 33 | ``` | 45 | ``` |
| 34 | $ make | 46 | $ ./build test |
| 35 | ``` | 47 | ``` |
| 36 | 48 | ||
| 37 | ## Running tests | 49 | For running the tests for the WebAssembly build with nodejs you can use: |
| 38 | |||
| 39 | This project includes a suite of "unit" test. They can be run with: | ||
| 40 | 50 | ||
| 41 | ``` | 51 | ``` |
| 42 | $ make test | 52 | $ ./build webtest |
| 43 | ``` | 53 | ``` |
| 44 | 54 | ||
| 45 | To run only a subset of the tests, set the `TEST` variable to a regular | 55 | To run only a subset of the tests, you can pass as argument a regular |
| 46 | expression that matches only the name of the tests you want to run: | 56 | expression that matches only the name of the tests you want to run: |
| 47 | 57 | ||
| 48 | ``` | 58 | ``` |
| 49 | $ TEST=coord make test | 59 | $ ./buld test coord |
| 50 | ``` | 60 | ``` |
| 51 | 61 | ||
| 52 | Each subfolder of the test folder contains a test. A test can consist | 62 | Each subfolder of the test folder contains a test. A test can consist |
| @@ -63,40 +73,36 @@ output, the results compared with the .out files) and test/last.err | |||
| 63 | Tests are always run in debug mode: this means that optimizations are | 73 | Tests are always run in debug mode: this means that optimizations are |
| 64 | disabled and some extra logging is enabled. | 74 | disabled and some extra logging is enabled. |
| 65 | 75 | ||
| 66 | See the test folder and test/test.sh for details. | ||
| 67 | |||
| 68 | ## Running "tools" | 76 | ## Running "tools" |
| 69 | 77 | ||
| 70 | In the tools folder there are some small programs that test various | 78 | In the tools folder there are some small programs that test various |
| 71 | functionality of the H48 library. They work similarly to test, but they | 79 | functionality of the H48 library. They work similarly to test, but they |
| 72 | are not run in debug mode by default. | 80 | are not run in debug mode by default. |
| 73 | 81 | ||
| 74 | To run a tool you must select it with the environment variable `TOOL`. | 82 | To run a tool you can use: |
| 75 | For example the command: | ||
| 76 | 83 | ||
| 77 | ``` | 84 | ``` |
| 78 | TOOL=stats make tool | 85 | $ ./build tool TOOLNAME PARAMETERS... |
| 79 | ``` | 86 | ``` |
| 80 | 87 | ||
| 81 | Will run the stats_tables_h48 tool. | 88 | Where `TOOLNAME` is the name of one of the tools, or a regular expression |
| 89 | that matches one, and `PARAMETERS...` is a tool-specific list of | ||
| 90 | parameters. | ||
| 82 | 91 | ||
| 83 | To pass some arguments to a tool, use the `TOOLARGS` variable: | 92 | For example: |
| 84 | 93 | ||
| 85 | ``` | 94 | ``` |
| 86 | TOOL=gendata TOOLARGS="h48 0;2;20" make tool | 95 | $ :./build tool gendata h48h2k2 |
| 87 | ``` | 96 | ``` |
| 88 | 97 | ||
| 89 | Like for tests, the value of the `TOOL` variable can be any regular | 98 | Will run a tool that generates the data table for the H48 solver with |
| 90 | expression matching the name of the tool. Unlike tests, one and | 99 | parameters `h=2` and `k=2. |
| 91 | only one tool will be selected for each run. The content of the | ||
| 92 | `TOOLARGS` variable is used directly as command line arguments for | ||
| 93 | the chosen tool. | ||
| 94 | 100 | ||
| 95 | Each tool run is automatically timed, so these tools can be used as | 101 | Each tool run is automatically timed, so these tools can be used as |
| 96 | benchmark. The output as well as the time of the run are saved to a | 102 | benchmark. The output as well as the time of the run are saved to a |
| 97 | file in the tools/results folder. | 103 | file in the tools/results folder. |
| 98 | 104 | ||
| 99 | To build and run a tool in debug mode, use `make debugtool`. | 105 | To build and run a tool in debug mode, use `./build -d tool`. |
| 100 | 106 | ||
| 101 | ## Command-line interface | 107 | ## Command-line interface |
| 102 | 108 | ||
| @@ -107,17 +113,11 @@ as the commands require quite verbose options. | |||
| 107 | To build the shell run: | 113 | To build the shell run: |
| 108 | 114 | ||
| 109 | ``` | 115 | ``` |
| 110 | $ make shell | 116 | $ ./build shell |
| 111 | ``` | ||
| 112 | |||
| 113 | This will create an executable called `run`. | ||
| 114 | Optionally, you can run some tests: | ||
| 115 | |||
| 116 | ``` | ||
| 117 | $ make shelltest | ||
| 118 | ``` | 117 | ``` |
| 119 | 118 | ||
| 120 | Then you can for example get a cube from a sequence of moves: | 119 | This will create an executable called `run`. Then you can for example |
| 120 | get a cube from a sequence of moves: | ||
| 121 | 121 | ||
| 122 | ``` | 122 | ``` |
| 123 | $ ./run frommoves -moves "R' U' F" | 123 | $ ./run frommoves -moves "R' U' F" |
| @@ -174,7 +174,8 @@ implementation file `nissy.cpp`. This interface wraps the calls to the | |||
| 174 | C functions in an object-oriented C++ interface for more convenient use. | 174 | C functions in an object-oriented C++ interface for more convenient use. |
| 175 | 175 | ||
| 176 | The `cpp/examples` folder contains some examples for how to use this | 176 | The `cpp/examples` folder contains some examples for how to use this |
| 177 | interface. You can build them and run them with the build tool, for example: | 177 | interface. You can build them and run them with the build tool, for |
| 178 | example: | ||
| 178 | 179 | ||
| 179 | ``` | 180 | ``` |
| 180 | ./build cpp cpp/examples/solve_h48h3k2.cpp | 181 | ./build cpp cpp/examples/solve_h48h3k2.cpp |
| @@ -192,18 +193,18 @@ this module follows the C API quite closely, except its functions | |||
| 192 | sometimes return strings instead of writing to `char *` buffers. | 193 | sometimes return strings instead of writing to `char *` buffers. |
| 193 | 194 | ||
| 194 | To build the Python module you need the Python development headers | 195 | To build the Python module you need the Python development headers |
| 195 | installed. You can check this from the output of `./configure.sh`: | 196 | installed. You can check this from the output of `./build config`: |
| 196 | 197 | ||
| 197 | ``` | 198 | ``` |
| 198 | $ ./configure.sh | 199 | $ ./build config |
| 199 | ... | 200 | ... |
| 200 | Python3 development libraries: version 3.12 | 201 | Python bindings: version 3.13 |
| 201 | ``` | 202 | ``` |
| 202 | 203 | ||
| 203 | Then to build the module: | 204 | Then to build the module: |
| 204 | 205 | ||
| 205 | ``` | 206 | ``` |
| 206 | $ make python | 207 | $ ./build python |
| 207 | ``` | 208 | ``` |
| 208 | 209 | ||
| 209 | And to import it | 210 | And to import it |
| @@ -240,14 +241,14 @@ Bindings for JavaScript via a WebAssembly build (using | |||
| 240 | The JavaScript module can be built with | 241 | The JavaScript module can be built with |
| 241 | 242 | ||
| 242 | ``` | 243 | ``` |
| 243 | ./build web | 244 | $ ./build web |
| 244 | ``` | 245 | ``` |
| 245 | 246 | ||
| 246 | Some examples can be found in the `web/examples` folder. They can be run | 247 | Some examples can be found in the `web/examples` folder. They can be run |
| 247 | using [nodejs](https://nodejs.org): | 248 | using [nodejs](https://nodejs.org): |
| 248 | 249 | ||
| 249 | ``` | 250 | ``` |
| 250 | node web/examples/[filename] | 251 | $ node web/examples/[filename] |
| 251 | ``` | 252 | ``` |
| 252 | 253 | ||
| 253 | ## Cube format | 254 | ## Cube format |
