aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorSebastiano Tronto <sebastiano@tronto.net>2025-05-16 15:43:09 +0200
committerSebastiano Tronto <sebastiano@tronto.net>2025-05-16 15:43:09 +0200
commit30b43f08955158d4f2066f4b50fe8d1241b3177b (patch)
treef2280c40a9ee721ac3223ec27e9ddbec6db224df /README.md
parentc2f3b1c9c534cadc81ebab3e718832d121cdf9cf (diff)
downloadnissy-core-30b43f08955158d4f2066f4b50fe8d1241b3177b.tar.gz
nissy-core-30b43f08955158d4f2066f4b50fe8d1241b3177b.zip
Remove configure + make build system.
This commit also updates the README, cleans up some stuff and fixes some oopsies.
Diffstat (limited to '')
-rw-r--r--README.md89
1 files changed, 45 insertions, 44 deletions
diff --git a/README.md b/README.md
index 6f3b9d2..4dd55b8 100644
--- a/README.md
+++ b/README.md
@@ -13,40 +13,50 @@ of pruning tables that were developed independently.
13 13
14## Building 14## Building
15 15
16First run the configuration script to detect the system configuration. 16This project currently supports only POSIX systems (Linux, MacOS, BSD...).
17This is going to select a C compiler and architecture-specific optimizations. 17If you want to build on Windows you can do so via
18[WSL](https://learn.microsoft.com/en-us/windows/wsl/install). Note that
19the resulting executable will not be a native Windows executable.
20Windows as a build target will be available in the future.
21
22To build nissy simply run
18 23
19``` 24```
20$ ./configure.sh 25$ ./build
21``` 26```
22 27
23These settings can be overridden, for example: 28For a list of options and targets for the build system run `./build help`.
29Some compiler settings can be overridden using environment variables,
30as explained in the comments at the beginning of the build script. For
31example, 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
29All the configuration-time options are described in the `configure.sh` script. 38is 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
31Once the configuration is done, you can build with make 43This 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 49For running the tests for the WebAssembly build with nodejs you can use:
38
39This 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
45To run only a subset of the tests, set the `TEST` variable to a regular 55To run only a subset of the tests, you can pass as argument a regular
46expression that matches only the name of the tests you want to run: 56expression 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
52Each subfolder of the test folder contains a test. A test can consist 62Each 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
63Tests are always run in debug mode: this means that optimizations are 73Tests are always run in debug mode: this means that optimizations are
64disabled and some extra logging is enabled. 74disabled and some extra logging is enabled.
65 75
66See the test folder and test/test.sh for details.
67
68## Running "tools" 76## Running "tools"
69 77
70In the tools folder there are some small programs that test various 78In the tools folder there are some small programs that test various
71functionality of the H48 library. They work similarly to test, but they 79functionality of the H48 library. They work similarly to test, but they
72are not run in debug mode by default. 80are not run in debug mode by default.
73 81
74To run a tool you must select it with the environment variable `TOOL`. 82To run a tool you can use:
75For example the command:
76 83
77``` 84```
78TOOL=stats make tool 85$ ./build tool TOOLNAME PARAMETERS...
79``` 86```
80 87
81Will run the stats_tables_h48 tool. 88Where `TOOLNAME` is the name of one of the tools, or a regular expression
89that matches one, and `PARAMETERS...` is a tool-specific list of
90parameters.
82 91
83To pass some arguments to a tool, use the `TOOLARGS` variable: 92For example:
84 93
85``` 94```
86TOOL=gendata TOOLARGS="h48 0;2;20" make tool 95$ :./build tool gendata h48h2k2
87``` 96```
88 97
89Like for tests, the value of the `TOOL` variable can be any regular 98Will run a tool that generates the data table for the H48 solver with
90expression matching the name of the tool. Unlike tests, one and 99parameters `h=2` and `k=2.
91only one tool will be selected for each run. The content of the
92`TOOLARGS` variable is used directly as command line arguments for
93the chosen tool.
94 100
95Each tool run is automatically timed, so these tools can be used as 101Each tool run is automatically timed, so these tools can be used as
96benchmark. The output as well as the time of the run are saved to a 102benchmark. The output as well as the time of the run are saved to a
97file in the tools/results folder. 103file in the tools/results folder.
98 104
99To build and run a tool in debug mode, use `make debugtool`. 105To 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.
107To build the shell run: 113To build the shell run:
108 114
109``` 115```
110$ make shell 116$ ./build shell
111```
112
113This will create an executable called `run`.
114Optionally, you can run some tests:
115
116```
117$ make shelltest
118``` 117```
119 118
120Then you can for example get a cube from a sequence of moves: 119This will create an executable called `run`. Then you can for example
120get 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
174C functions in an object-oriented C++ interface for more convenient use. 174C functions in an object-oriented C++ interface for more convenient use.
175 175
176The `cpp/examples` folder contains some examples for how to use this 176The `cpp/examples` folder contains some examples for how to use this
177interface. You can build them and run them with the build tool, for example: 177interface. You can build them and run them with the build tool, for
178example:
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
192sometimes return strings instead of writing to `char *` buffers. 193sometimes return strings instead of writing to `char *` buffers.
193 194
194To build the Python module you need the Python development headers 195To build the Python module you need the Python development headers
195installed. You can check this from the output of `./configure.sh`: 196installed. You can check this from the output of `./build config`:
196 197
197``` 198```
198$ ./configure.sh 199$ ./build config
199... 200...
200Python3 development libraries: version 3.12 201Python bindings: version 3.13
201``` 202```
202 203
203Then to build the module: 204Then to build the module:
204 205
205``` 206```
206$ make python 207$ ./build python
207``` 208```
208 209
209And to import it 210And to import it
@@ -240,14 +241,14 @@ Bindings for JavaScript via a WebAssembly build (using
240The JavaScript module can be built with 241The JavaScript module can be built with
241 242
242``` 243```
243./build web 244$ ./build web
244``` 245```
245 246
246Some examples can be found in the `web/examples` folder. They can be run 247Some examples can be found in the `web/examples` folder. They can be run
247using [nodejs](https://nodejs.org): 248using [nodejs](https://nodejs.org):
248 249
249``` 250```
250node web/examples/[filename] 251$ node web/examples/[filename]
251``` 252```
252 253
253## Cube format 254## Cube format

Generated with cgit - Back to sebastiano.tronto.net