mirror of
https://github.com/vimpunk/mio.git
synced 2025-12-06 16:57:01 +08:00
First draft of README extensions
This commit is contained in:
Austin McCartney
parent
d5f411e304
commit
05085ab7a0
139
README.md
139
README.md
@ -156,19 +156,138 @@ using mmap_sink = mio::basic_mmap_sink<std::byte>;
|
||||
|
||||
Though generally not needed, since mio maps users requested offsets to page boundaries, you can query the underlying system's page allocation granularity by invoking `mio::page_size()`, which is located in `mio/page.hpp`.
|
||||
|
||||
### Installation
|
||||
mio is a header-only library, so just copy the contents in `mio/include` into your system wide include path, such as `/usr/include`, or into your project's lib folder.
|
||||
|
||||
## CMake
|
||||
A `CMakeLists.txt` is provided to allow easy git submodule usage or installation.
|
||||
A `CMakeLists.txt` file is provided to allow easy testing, installation, and subproject composition on many platforms and operating systems.
|
||||
|
||||
To use as a submodule, clone mio within your project's dependencies/externals folder and add:
|
||||
### Testing
|
||||
Mio provides a small test suite and example.
|
||||
When mio is configured as the highest level CMake project, these tests are built by default.
|
||||
CMake supports a number of backends for compilation and linking.
|
||||
|
||||
To use a static configuration build tool, such as GNU Make or Ninja:
|
||||
|
||||
```sh
|
||||
cd <mio source directory>
|
||||
mkdir build
|
||||
cd build
|
||||
|
||||
# Configure the build...
|
||||
cmake -D CMAKE_BUILD_TYPE=<Debug | Release> \
|
||||
-G <"Unix Makefiles" | "Ninja"> ..
|
||||
|
||||
# build the tests...
|
||||
< make | ninja | cmake --build . >
|
||||
|
||||
# run the tests...
|
||||
< make test | ninja test | cmake --build . --target test | ctest >
|
||||
```
|
||||
add_subdirectory( dependencies_folder/mio )
|
||||
target_link_libraries( MyCoolProject mio )
|
||||
|
||||
To use a dynamic configuration build tool, such as Visual Studio or Xcode:
|
||||
|
||||
```sh
|
||||
cd <mio source directory>
|
||||
mkdir build
|
||||
cd build
|
||||
|
||||
# Configure the build...
|
||||
cmake -G <"Visual Studio 14 2015 Win64" | "Xcode"> ..
|
||||
|
||||
# build the tests...
|
||||
cmake --build . --config <Debug | Release>
|
||||
|
||||
# run the tests via
|
||||
ctest --build-config <Debug | Release>
|
||||
|
||||
# ... or via CMake build tool mode...
|
||||
cmake --build . --config <Debug | Release> --target test
|
||||
```
|
||||
to your project's `CMakeLists.txt` to add mio into `MyCoolProject`'s include-space.
|
||||
|
||||
To install, do an out-of-source build(such as making a `build` folder and running `cmake ..` inside of it) and then run `sudo make install` to copy relevant include files to
|
||||
Of course the build and test steps can also be executed via the `all` and `test` targets, respectively, from within the IDE after opening the project file generated during the configuration step.
|
||||
|
||||
The optional `BUILD_TESTS` option can be used to build unit tests(off by default) by instead using `cmake -DBUILD_TESTS=ON ..`
|
||||
Mio's testing is also configured to operate as a client to the [CDash](https://www.cdash.org/) software quality dashboard application. Please see the [Kitware documentation](https://cmake.org/cmake/help/latest/manual/ctest.1.html#dashboard-client) for more information on this mode of operation.
|
||||
|
||||
### Installation
|
||||
|
||||
Mio provides build system provides an installation target and support for downstream consumption via CMake's `find_package` intrinsic function.
|
||||
CMake allows installation to an arbitrary location, which may be specified by defining `CMAKE_INSTALL_PREFIX` at configure time.
|
||||
In the absense of a user specification, CMake will install mio to conventional location based on the system operating system.
|
||||
|
||||
To use a static configuration build tool, such as GNU Make or Ninja:
|
||||
|
||||
```sh
|
||||
cd <mio source directory>
|
||||
mkdir build
|
||||
cd build
|
||||
|
||||
# Configure the build...
|
||||
cmake [-D CMAKE_INSTALL_PREFIX="path/to/installation"] \
|
||||
-D CMAKE_BUILD_TYPE=Release \
|
||||
-G <"Unix Makefiles" | "Ninja"> ..
|
||||
|
||||
# build and install mio
|
||||
[sudo] < make install | ninja install | cmake --build . --target install>
|
||||
```
|
||||
|
||||
To use a dynamic configuration build tool, such as Visual Studio or Xcode:
|
||||
|
||||
```sh
|
||||
cd <mio source directory>
|
||||
mkdir build
|
||||
cd build
|
||||
|
||||
# Configure the build...
|
||||
cmake [-D CMAKE_INSTALL_PREFIX="path/to/installation"] \
|
||||
-G <"Visual Studio 14 2015 Win64" | "Xcode"> ..
|
||||
|
||||
# build the tests...
|
||||
cmake --build . --config Release --target install
|
||||
```
|
||||
|
||||
This installation
|
||||
+ copies the mio header files to the `include/mio` subdirectory of the installation root
|
||||
+ generates and copies several CMake configuration files (`mioConfig.cmake`, `mioConfig-Release.cmake`, and `mioConfigVersion.cmake`) to the `share/cmake/mio` subdirectory root.
|
||||
|
||||
This latter step allows downstream CMake projects to consume mio via `find_package`, e.g.
|
||||
|
||||
```cmake
|
||||
find_package( mio REQUIRED )
|
||||
target_link_libraries( MyTarget PUBLIC mio::mio )
|
||||
```
|
||||
|
||||
If mio was installed to a non-conventional location, it may be necessary to specify the installation root directory via either
|
||||
+ the `CMAKE_PREFIX_PATH` configuration option,
|
||||
+ the `CMAKE_PREFIX_PATH` environment variable, or
|
||||
+ `mio_DIR` environment variable.
|
||||
Please see the [Kitware documentation](https://cmake.org/cmake/help/v3.0/command/find_package.html) for more information.
|
||||
|
||||
In addition, mio supports packaged relocatable installations via [CPack](https://cmake.org/cmake/help/latest/manual/cpack.1.html. Following configuration, from the build directory, invoke cpack as follows to generate a packaged installation:
|
||||
|
||||
```sh
|
||||
cpack -G <generator name> -C Release
|
||||
```
|
||||
|
||||
The list of supported generators varies from platform to platform. See the output of `cpack --help` for a complete list of supported generators on your platform.
|
||||
|
||||
### Subproject Composition
|
||||
To use mio as a subproject, copy the mio repository to your project's dependencies/externals folder.
|
||||
If your project is version controlled using git, a git submodule or git subtree can be used to syncronize with the updstream repository.
|
||||
The [use](https://services.github.com/on-demand/downloads/submodule-vs-subtree-cheat-sheet/) and [relative advantages](https://andrey.nering.com.br/2016/git-submodules-vs-subtrees/) of these git facilities is beyond the scope of this document, but in brief, each may be established as follows:
|
||||
|
||||
```sh
|
||||
# via git submodule
|
||||
cd <my project's dependencies directory>
|
||||
git submodule add -b master https://github.com/mandreyel/mio.git
|
||||
|
||||
# via git subtree
|
||||
cd <my project's root directory>
|
||||
git subtree add --prefix <relative path to dependencies directory>/mio https://github.com/mandreyel/mio.git master --squash
|
||||
```
|
||||
|
||||
Given a mio subdirectory in a project, simply add the following lines to your project's to add mio into `MyTarget` include directories.
|
||||
|
||||
```cmake
|
||||
add_subdirectory( path/to/mio/ )
|
||||
target_link_libraries( MyTarget PUBLIC <mio::mio | mio> )
|
||||
```
|
||||
|
||||
Note that, as a subproject, mio's tests and examples will not be built and CPack integration is deferred to the host project.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user