Skip to content

Commit 5b1e968

Browse files
leerholeerho
authored
Merge pull request #472 from apache/tisonkun-patch-1
Refactor README for clarity and consistency
2 parents 7a2f9e3 + 2136239 commit 5b1e968

File tree

1 file changed

+66
-73
lines changed

1 file changed

+66
-73
lines changed

‎README.md‎

Lines changed: 66 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -1,106 +1,99 @@
11
# Apache DataSketches Core C++ Library Component
2-
This is the core C++ component of the Apache DataSketches library. It contains all of the key sketching algorithms that are in the Java component and can be accessed directly from user applications.
32

4-
This component is also a dependency of other components of the library that create adaptors for target systems, such as PostgreSQL.
3+
This is the core C++ component of the Apache DataSketches library. It contains all the key sketching algorithms from the Java implementation and can be accessed directly by user applications.
54

6-
Note that we have a parallel core component for [Java]((https://github.com/apache/datasketches-java) and [Python]((https://github.com/apache/datasketches-python) implementations of the same sketch algorithms.
5+
This component is also a dependency of other library components that create adaptors for target systems, such as [PostgreSQL](https://github.com/apache/datasketches-postgresql).
6+
7+
Note that we have parallel core library components for Java, Python, and GO implementations of many of the same sketch algorithms:
8+
9+
- [datasketches-java](https://github.com/apache/datasketches-java)
10+
- [datasketches-python](https://github.com/apache/datasketches-python)
11+
- [datasketches-go](https://github.com/apache/datasketches-go)
712

813
Please visit the main [Apache DataSketches website](https://datasketches.apache.org) for more information.
914

10-
If you are interested in making contributions to this site please see our [Community](https://datasketches.apache.org/docs/Community/) page for how to contact us.
15+
If you are interested in making contributions to this site, please see our [Community](https://datasketches.apache.org/docs/Community/) page for how to contact us.
1116

1217
---
1318

1419
This code requires C++11.
1520

16-
This library is header-only. The build process provided is only for building unit tests.
21+
This library is header-only. The provided build process is only for unit tests.
1722

18-
Building the unit tests requires cmake 3.12.0 or higher.
23+
Building the unit tests requires CMake 3.12.0 or higher.
1924

20-
Installing the latest cmake on OSX: brew install cmake
25+
Installing the latest CMake on OSX: `brew install cmake`.
2126

22-
Building and running unit tests using cmake for OSX and Linux:
27+
Building and running unit tests using CMake for OSX and Linux:
2328

24-
```
25-
$ cmake -S . -B build/Release -DCMAKE_BUILD_TYPE=Release
26-
$ cmake --build build/Release -t all test
29+
```shell
30+
cmake -S . -B build/Release -DCMAKE_BUILD_TYPE=Release
31+
cmake --build build/Release -t all test
2732
```
2833

29-
Building and running unit tests using cmake for Windows from the command line:
34+
Building and running unit tests using CMake for Windows from the command line:
3035

31-
```
32-
$ cd build
33-
$ cmake ..
34-
$ cd ..
35-
$ cmake --build build --config Release
36-
$ cmake --build build --config Release --target RUN_TESTS
36+
```shell
37+
cd build
38+
cmake ..
39+
cd ..
40+
cmake --build build --config Release
41+
cmake --build build --config Release --target RUN_TESTS
3742
```
3843

39-
To install a local distribution (OSX and Linux), use the following command. The
40-
CMAKE_INSTALL_PREFIX variable controls the destination. If not specified, it
41-
defaults to installing in /usr (/usr/include, /usr/lib, etc). In the command below,
42-
the installation will be in /tmp/install/DataSketches (/tmp/install/DataSketches/include,
43-
/tmp/install/DataSketches/lib, etc)
44+
To install a local distribution (OSX and Linux), use the following command. The `CMAKE_INSTALL_PREFIX` variable controls the destination. If not specified, it defaults to installing in /usr (/usr/include, /usr/lib, etc). In the command below, the installation will be in /tmp/install/DataSketches (/tmp/install/DataSketches/include, /tmp/install/DataSketches/lib, etc).
4445

45-
```
46-
$ cmake -S . -B build/Release -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/tmp/install/DataSketches
47-
$ cmake --build build/Release -t install
46+
```shell
47+
cmake -S . -B build/Release -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/tmp/install/DataSketches
48+
cmake --build build/Release -t install
4849
```
4950

50-
To generate an installable package using cmake's built in cpack packaging tool,
51-
use the following command. The type of packaging is controlled by the CPACK_GENERATOR
52-
variable (semi-colon separated list). Cmake usually supports packaging types such as RPM,
53-
DEB, STGZ, TGZ, TZ, ZIP, etc.
51+
To generate an installable package using CMake's built-in cpack packaging tool, use the following command. The type of packaging is controlled by the `CPACK_GENERATOR` variable (semi-colon separated list). CMake usually supports packaging formats such as RPM, DEB, STGZ, TGZ, TZ, and ZIP.
5452

55-
```
56-
$ cmake3 -S . -B build/Release -DCMAKE_BUILD_TYPE=Release -DCPACK_GENERATOR="RPM;STGZ;TGZ"
57-
$ cmake3 --build build/Release -t package
53+
```shell
54+
cmake -S . -B build/Release -DCMAKE_BUILD_TYPE=Release -DCPACK_GENERATOR="RPM;STGZ;TGZ"
55+
cmake --build build/Release -t package
5856
```
5957

6058
The DataSketches project can be included in other projects' CMakeLists.txt files in one of two ways.
61-
If DataSketches has been installed on the host (using an RPM, DEB, "make install" into /usr/local, or some
62-
way, then CMake's `find_package` command can be used like this:
6359

64-
```
65-
find_package(DataSketches 3.2 REQUIRED)
66-
target_link_library(my_dependent_target PUBLIC ${DATASKETCHES_LIB})
60+
If DataSketches has been installed on the host (using an RPM, DEB, "make install" into /usr/local, or some way, then CMake's `find_package` command can be used like this:
61+
62+
```cmake
63+
find_package(DataSketches 3.2 REQUIRED)
64+
target_link_library(my_dependent_target PUBLIC ${DATASKETCHES_LIB})
6765
```
6866

6967
When used with find_package, DataSketches exports several variables, including
7068

71-
- `DATASKETCHES_VERSION`: The version number of the datasketches package that was imported.
72-
- `DATASKETCHES_INCLUDE_DIR`: The directory that should be added to access DataSketches include files.
73-
Because cmake automatically includes the interface directories for included target libraries when
74-
using `target_link_library`, under normal circumstances there will be no need to include this directly.
75-
- `DATASKETCHES_LIB`: The name of the DataSketches target to include as a dependency. Projects pulling
76-
in DataSketches should reference this with `target_link_library` in order to set up all the correct dependencies
77-
and include paths.
78-
79-
If you don't have DataSketches installed locally, dependent projects can pull it directly
80-
from GitHub using CMake's `ExternalProject` module. The code would look something like this:
81-
82-
```
83-
cmake_policy(SET CMP0097 NEW)
84-
include(ExternalProject)
85-
ExternalProject_Add(datasketches
86-
GIT_REPOSITORY https://github.com/apache/datasketches-cpp.git
87-
GIT_TAG 3.2.0
88-
GIT_SHALLOW true
89-
GIT_SUBMODULES ""
90-
INSTALL_DIR /tmp/datasketches-prefix
91-
CMAKE_ARGS -DBUILD_TESTS=OFF -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} -DCMAKE_INSTALL_PREFIX=/tmp/datasketches-prefix
92-
93-
# Override the install command to add DESTDIR
94-
# This is necessary to work around an oddity in the RPM (but not other) package
95-
# generation, as CMake otherwise picks up the Datasketch files when building
96-
# an RPM for a dependent package. (RPM scans the directory for files in addition to installing
97-
# those files referenced in an "install" rule in the cmake file)
98-
INSTALL_COMMAND env DESTDIR= ${CMAKE_COMMAND} --build . --target install
99-
)
100-
ExternalProject_Get_property(datasketches INSTALL_DIR)
101-
set(datasketches_INSTALL_DIR ${INSTALL_DIR})
102-
message("Source dir of datasketches = ${datasketches_INSTALL_DIR}")
103-
target_include_directories(my_dependent_target
104-
PRIVATE ${datasketches_INSTALL_DIR}/include/DataSketches)
105-
add_dependencies(my_dependent_target datasketches)
69+
- `DATASKETCHES_VERSION`: The version number of the datasketches package that was imported.
70+
- `DATASKETCHES_INCLUDE_DIR`: The directory that should be added to access DataSketches include files. Because CMake automatically includes the interface directories for included target libraries when using `target_link_library`, under normal circumstances, there will be no need to include this directly
71+
- `DATASKETCHES_LIB`: The name of the DataSketches target to include as a dependency. Projects pulling in DataSketches should reference this with `target_link_library` in order to set up all the correct dependencies and include paths.
72+
73+
If you don't have DataSketches installed locally, dependent projects can pull it directly from GitHub using CMake's `ExternalProject` module. The code would look something like this:
74+
75+
```cmake
76+
cmake_policy(SET CMP0097 NEW)
77+
include(ExternalProject)
78+
ExternalProject_Add(datasketches
79+
GIT_REPOSITORY https://github.com/apache/datasketches-cpp.git
80+
GIT_TAG 3.2.0
81+
GIT_SHALLOW true
82+
GIT_SUBMODULES ""
83+
INSTALL_DIR /tmp/datasketches-prefix
84+
CMAKE_ARGS -DBUILD_TESTS=OFF -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} -DCMAKE_INSTALL_PREFIX=/tmp/datasketches-prefix
85+
86+
# Override the install command to add DESTDIR
87+
# This is necessary to work around an oddity in the RPM (but not other) package
88+
# generation, as CMake otherwise picks up the Datasketch files when building
89+
# an RPM for a dependent package. (RPM scans the directory for files in addition to installing
90+
# those files referenced in an "install" rule in the cmake file)
91+
INSTALL_COMMAND env DESTDIR= ${CMAKE_COMMAND} --build . --target install
92+
)
93+
ExternalProject_Get_property(datasketches INSTALL_DIR)
94+
set(datasketches_INSTALL_DIR ${INSTALL_DIR})
95+
message("Source dir of datasketches = ${datasketches_INSTALL_DIR}")
96+
target_include_directories(my_dependent_target
97+
PRIVATE ${datasketches_INSTALL_DIR}/include/DataSketches)
98+
add_dependencies(my_dependent_target datasketches)
10699
```

0 commit comments

Comments
 (0)