Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update installation instructions for CMake #270

Merged
merged 2 commits into from
Jul 22, 2024
Merged

Update installation instructions for CMake #270

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1f18fdf
Update installation instructions for CMake
chiphogg Jul 22, 2024
0369c7c
Clean up instructions
chiphogg Jul 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 98 additions & 28 deletions docs/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,40 +33,42 @@ Here's an overview of the tradeoffs involved.
<tr>
<th rowspan=2></th>
<th colspan=2>Single File</th>
<th colspan=2>Full Install</th>
<th colspan=3>Full Install</th>
</tr>
<tr>
<td>Pre-built</td>
<td>Custom</td>
<td>bazel</td>
<td>CMake, conan, vcpkg, ...</td>
<td>CMake</td>
<td>conan, vcpkg, ...</td>
</tr>
<tr>
<td>Setup time</td>
<td class="best">~1 min</td>
<td class="good">~10 min</td>
<td class="good">~10 min</td>
<td class="good">~10 min</td>
<td class="poor">Not <i>yet</i> supported<br>(use <b>single-file</b> instead for now)</td>
</tr>
<tr>
<td>Unit selection</td>
<td class="fair">Base units only<br>(or too many units)</td>
<td class="good">Any units desired</td>
<td colspan=2 class="best">Any units desired, <i>without</i> needing "reinstall"</td>
<td colspan=3 class="best">Any units desired, <i>without</i> needing "reinstall"</td>
</tr>
<tr>
<td>Compile time cost</td>
<td class="good">~10 units</td>
<td class="good">Very competitive up to a few dozen units</td>
<td colspan=2 class="best"><i>Each file</i> only pays for the units it uses</td>
<td colspan=3 class="best"><i>Each file</i> only pays for the units it uses</td>
</tr>
<tr>
<td>Flexibility</td>
<td colspan=2 class="fair">
Awkward: would need to download <pre>io.hh</pre> and/or <pre>testing.hh</pre> separately, and
modify their includes manually
</td>
<td colspan=2 class="best">
<td colspan=3 class="best">
Include I/O, testing utilities, individual units as desired, on a per-file basis
</td>
</tr>
Expand All @@ -87,6 +89,7 @@ SetupTime -->|No! Just let me start!| UsePreBuilt
SetupTime -->|Sure| UseCustom
Usage -->|Ready to use in my project!| BuildSystem
BuildSystem -->|bazel| UseFullInstall
BuildSystem -->|CMake| UseFullInstall
BuildSystem -->|other| UseCustom
```

Expand Down Expand Up @@ -243,38 +246,105 @@ attribute, and include the appropriate files.

| Dependency | Headers provided | Notes |
|------------|------------------|-------|
| `@au//au` | `"au/au.hh"`<br>`"au/units.*.hh"` | Core library functionality. See [all available units](https://github.com/aurora-opensource/au/tree/main/au/units) |
| `@au//au` | `"au/au.hh"`<br>`"au/units/*.hh"` | Core library functionality. See [all available units](https://github.com/aurora-opensource/au/tree/main/au/units) |
| `@au//au:io` | `"au/io.hh"` | `operator<<` support |
| `@au//au:testing` | `"au/testing.hh"` | Utilities for testing<br>_Note:_ `testonly = True` |
| `@au//au:testing` | `"au/testing.hh"` | Utilities for writing googletest tests<br>_Note:_ `testonly = True` |

#### CMake

CMake support is still experimental and in-progress. We are building it up starting from "root"
targets (that is, targets without dependencies), and expanding support to the rest of the library.
There are two ways to include the Au library in your CMake project.

To build the library using this experimental CMake support, follow these steps:
1. **(Recommended)** Use the `FetchContent` module to download the library directly from GitHub.

```sh
# CMake is a "meta build system", not a build system.
# This first command generates the actual build files.
cmake -S . -B cmake/build -DCMAKE_VERIFY_INTERFACE_HEADER_SETS=TRUE
2. Install the library to the system, and use `find_package`.

# This command builds Au, checks include paths, and runs unit tests.
cmake \
--build cmake/build \
--target \
all \
all_verify_interface_header_sets \
test
```
The reason we recommend `FetchContent` is because it makes it easier for each project to get the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This wording is a little clunky. It might be clearer to write something like

We recommend `FetchContent` because it gets the exact version and installs au for the project.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tweaked it a little bit based on your recommendation.

exact version of Au they need. `FetchContent` also means you don't need to manually clone the Au
repo, or build and run the tests. On the other hand, if you want a single global system-wide
version of Au, then you can install it to the system, and simply use `find_package`.

In either case, here are the main targets and include files provided by the Au library:

#### Other build systems (CMake / conan / vcpkg / ...)
| Target | Headers provided | Notes |
|--------|------------------|-------|
| `Au::au` | `"au/au.hh"`<br>`"au/units/*.hh"` | Core library functionality. See [all available units](https://github.com/aurora-opensource/au/tree/main/au/units) |
| `Au::io` | `"au/io.hh"` | `operator<<` support |
| `Au::testing` | `"au/testing.hh"` | Utilities for writing googletest tests |

We would like to support all these build and packaging systems, and perhaps others! But the initial
public release is bazel-only, because bazel is what we use at Aurora, and we don't have experience
with any of these alternatives. Thus, we'll need to lean on the community to support them.
Now, here are the installation instructions.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't like the word Now and these are all installation instructions. It might be better to delete this line.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.


!!! note
These instructions are for adding Au to a _project_ that uses CMake, not building Au itself
using CMake.

Au is a bazel-first project, so most Au development would normally be done using bazel.
However, we do have instructions for doing this with CMake as well: see the `find_package` tab
below.

=== "Using `FetchContent`"
Add the following to your `CMakeLists.txt` file:

```cmake
include(FetchContent)
FetchContent_Declare(
Au
GIT_REPOSITORY https://github.com/aurora-opensource/au
GIT_TAG "main" # Or a specific tag.
EXCLUDE_FROM_ALL
)
FetchContent_MakeAvailable(Au)
```

You should now be able to depend on Au targets, such as `Au::au` or `Au::io`, and include their
corresponding headers, such as `#include "au/au.hh"` or `#include "au/io.hh"`.

=== "Using `find_package`"
Before you can use `find_package`, you need to install the library to your system. This means
cloning the repo, building the library, running the tests, and installing it.

First, clone the repository.

```sh
git clone https://github.com/aurora-opensource/au.git
cd au
```

Meanwhile, the library itself is still at least partially available on all build environments, via
the single-file options explained above.
If you want a specific release, check out the tag you want. Note that the first version of Au
that supports CMake will be 0.3.5.

```sh
# Optional, but recommended:
git checkout "0.3.5" # Or whichever tag you prefer.
```

Now, build and test the library. These commands will include both the explicit tests, and also
several CMake-generated tests to make sure that the includes are set up correctly.

```sh
# CMake is a "meta build system", not a build system.
# This first command generates the actual build files.
cmake -S . -B cmake/build -DCMAKE_VERIFY_INTERFACE_HEADER_SETS=TRUE

# This command builds Au, checks include paths, and runs unit tests.
cmake \
--build cmake/build \
--target \
all \
all_verify_interface_header_sets \
test
```

If the tests pass, you can install the library to your system.

```sh
sudo cmake --install cmake/build
```

At this point, the `Au` CMake library is installed to your system, and can be found via the
usual `find_package` mechanism!

```cmake
find_package(Au)
```

<script src="../assets/hrh4.js" async=false defer=false></script>
Loading