ext/h3/src/README.md in h3-3.6.2 vs ext/h3/src/README.md in h3-3.7.1
- old
+ new
@@ -1,26 +1,29 @@
<img align="right" src="https://uber.github.io/img/h3Logo-color.svg" alt="H3 Logo" width="200">
# H3: A Hexagonal Hierarchical Geospatial Indexing System
-[](https://travis-ci.com/uber/h3)
-[](https://ci.appveyor.com/project/Uber/h3/branch/master)
+[](https://github.com/uber/h3/actions)
+[](https://github.com/uber/h3/actions)
+[](https://github.com/uber/h3/actions)
+[](https://github.com/uber/h3/actions)
[](https://coveralls.io/github/uber/h3?branch=master)
[](LICENSE)
H3 is a geospatial indexing system using a hexagonal grid that can be (approximately) subdivided into finer and finer hexagonal grids, combining the benefits of a hexagonal grid with [S2](https://code.google.com/archive/p/s2-geometry-library/)'s hierarchical subdivisions.
-Documentation is available at [https://uber.github.io/h3/](https://uber.github.io/h3/). Developer documentation in Markdown format is available under the [dev-docs](./dev-docs/) directory.
+Documentation is available at [https://h3geo.org/](https://h3geo.org/). Developer documentation in Markdown format is available under the [dev-docs](./dev-docs/) directory.
* Post **bug reports or feature requests** to the [GitHub Issues page](https://github.com/uber/h3/issues)
* Ask **questions** by posting to the [H3 tag on StackOverflow](https://stackoverflow.com/questions/tagged/h3)
+ * There is also an [H3 Slack workspace](https://join.slack.com/t/h3-core/shared_invite/zt-g6u5r1hf-W_~uVJmfeiWtMQuBGc1NNg)
## Installing
-We recommend using prebuilt bindings if they are available for your programming language. Bindings for [Go](https://github.com/uber/h3-go), [Java](https://github.com/uber/h3-java), [JavaScript](https://github.com/uber/h3-js), [Python](https://github.com/uber/h3-py), and [others](https://uber.github.io/h3/#/documentation/community/bindings) are available.
+We recommend using prebuilt bindings if they are available for your programming language. Bindings for [Go](https://github.com/uber/h3-go), [Java](https://github.com/uber/h3-java), [JavaScript](https://github.com/uber/h3-js), [Python](https://github.com/uber/h3-py), and [others](https://h3geo.org/docs/community/bindings) are available.
-On macOS, you can install H3 using brew:
+On macOS, you can install H3 using `brew`:
```
brew install h3
```
Otherwise, to build H3 from source, please see the following instructions.
@@ -28,11 +31,11 @@
Still here? To build the H3 C library, you'll need a C compiler (tested with `gcc` and `clang`), [CMake](https://cmake.org/), and [Make](https://www.gnu.org/software/make/). If you intend to contribute to H3, you must have [clang-format](https://clang.llvm.org/docs/ClangFormat.html) installed and we recommend installing [ccmake](https://cmake.org/cmake/help/v3.0/manual/ccmake.1.html) and [LCOV](http://ltp.sourceforge.net/coverage/lcov.php) to configure the `cmake` arguments to build and run the tests and generate the code coverage report. We also recommend using `gcc` for the code coverage as some versions of `clang` generate annotations that aren't compatible with `lcov`. [Doxygen](http://www.stack.nl/~dimitri/doxygen/) is needed to build the API documentation.
#### Install build-time dependencies
-* Alpine
+* Alpine
```
# Installing the bare build requirements
apk add cmake make gcc libtool musl-dev
```
@@ -43,11 +46,11 @@
sudo apt install cmake make gcc libtool
# Installing useful tools for development
sudo apt install clang-format cmake-curses-gui lcov doxygen
```
-* macOS (using brew)
+* macOS (using `brew`)
First make sure you [have the developer tools installed](http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/) and then
```
# Installing the bare build requirements
@@ -58,27 +61,74 @@
* Windows (Visual Studio)
You will need to install CMake and Visual Studio, including the Visual C++ compiler. For building on Windows, please follow the [Windows build instructions](dev-docs/build_windows.md).
+* FreeBSD
+
+ ```
+# Installing the build requirements
+sudo pkg install bash cmake gmake doxygen lcov
+```
+
#### Compilation
-From the repository you would then compile like so:
+From the repository root, you can compile H3 with:
```
-cmake .
+mkdir build
+cd build
+cmake ..
make
```
+All subsequent `make` commands should be run from within the `build` directory.
+
+**Note**: There are several ways to build H3 with CMake; the method above is just one example that restricts all build artifacts to the `build` directory.
+
You can install system-wide with:
```
sudo make install
```
+If using the method above, from the repository root, you can clean all build artifacts with:
+
+```
+rm -rf build
+```
+
#### Testing
-After making the project, you can test with `make test`, and if `lcov` is installed you can `make coverage` to generate a code coverage report.
+After making the project, you can test with `make test`.
+You can run a faster test suite that excludes the most expensive tests with `make test-fast`.
+
+#### Coverage
+
+You can generate a code coverage report if `lcov` is installed, and if the project was built with the `CMAKE_BUILD_TYPE=Debug` option.
+For example, from a clean repository, you could run:
+
+```
+mkdir build
+cd build
+cmake -DCMAKE_BUILD_TYPE=Debug ..
+make
+make coverage
+```
+
+You can then view a detailed HTML coverage report by opening `coverage/index.html` in your browser.
+
+#### Benchmarks
+
+You can run timing benchmarks by building with the `CMAKE_BUILD_TYPE=Release`, and running `make benchmarks`:
+
+```
+mkdir build
+cd build
+cmake -DCMAKE_BUILD_TYPE=Release ..
+make
+make benchmarks
+```
#### Documentation
You can build developer documentation with `make docs` if Doxygen was installed when CMake was run. Index of the documentation will be `dev-docs/_build/html/index.html`.