mirror of
https://github.com/JakeHillion/object-introspection.git
synced 2024-11-09 21:24:14 +00:00
fe9b4b232a
OI's build is challenging and has often been a problem for the Open Source community. It requires an extremely specific set of dependencies that are very hard to achieve on most systems. There are frequent breakages, like when updating to CentOS Stream 9, or when trying to update the CI's clang from clang-12 to clang-15 - OI requires the clang libraries to be version 15 but can't be compiled with it on the CI! This changes provides a mostly working build environment with `nix`. This environment is pinned to a specific nixpkgs revision using `flake.lock`, and only updates when we explicitly tell it to. Summary of changes: - Update CMakeLists.txt required version to 3.24. This allows specifying `FIND_PACKAGE_ARGS` in `FetchContent`, meaning we can use system packages. This is available on most up to date distros (3.30.2 is current). - Extends `flake.nix` to be able to build OI. Adds instructions for building and developing OI using `nix`. - Partially runs the tests in GitHub Actions. A huge amount must be excluded because of incompatibilites between the clangStdenv compiler and drgn. We have similar, though fewer, issues when building with the clang-12/libstdcxx mix on the Ubuntu 22.04 CircleCI, though this is at least reproducible. - Updates CircleCI to build CMake from source as we don't have a newer image available. Also add some newly found dependencies (not sure how it was working without them before). Test plan: This change requires less testing than previous build related changes because it deprecates most of the build types. - The internal BUCK build is unaffected. No special testing. - The semi-internal CMake build is gone. Use Nix. - The Nix build for clang-15 and some tests are continuously tested in GitHub actions. - Tested the set of Nix commands in the README. All work except the one that points to GitHub as this must be merged first. - The existing CircleCI runs on Ubuntu 20.04 are maintained. - Unable to test the new `test-report.yml` as it must be merged due to the permissions it needs. Will follow up with testing after this is merged. See: https://github.com/dorny/test-reporter?tab=readme-ov-file#recommended-setup-for-public-repositories The list of exclusions for GitHub Actions/nix testing is currently very long, I think 29% of the tests. This should be stable and reproducible though, and likely needs deep changes to OI to fix. That's why fixes are excluded from this PR. It's all to do with the forked drgn not being able to parse clang's newer DWARF output, and can't be fixed by rolling back as we required a relatively new libcxx.
75 lines
3.2 KiB
Markdown
75 lines
3.2 KiB
Markdown
# object-introspection
|
|
|
|
[](https://matrix.to/#/#object-introspection:matrix.org)
|
|
[](https://youtu.be/6IlTs8YRne0)
|
|
|
|
|
|
|
|
Object Introspection is a memory profiling technology for C++ objects. It provides the ability to dynamically instrument applications to capture the precise memory occupancy of entire object hierarchies including all containers and dynamic allocations. All this with no code modification or recompilation!
|
|
|
|
For more information on the technology and how to get started applying it to your applications please check out the [Object Introspection](https://objectintrospection.org/) website.
|
|
|
|
## Join the Object Introspection community
|
|
See the [CONTRIBUTING](CONTRIBUTING.md) file for how to help out.
|
|
|
|
## License
|
|
Object Introspection is licensed under the [Apache 2.0 License](LICENSE).
|
|
|
|
## Getting started with Nix
|
|
|
|
Nix is the easiest way to get started with `oid` as it is non-trivial to build otherwise. Explicit Nix support for Object Introspection as a Library will come down the line, but Nix can currently provide you a reproducible development environment in which to build it.
|
|
|
|
These examples expect you to have `nix` installed and available with no other dependencies required. Find the installation guide at https://nixos.org/download.html.
|
|
|
|
We also required flake support. To enable flakes globally run:
|
|
|
|
$ mkdir -p ~/.config/nix
|
|
$ echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
|
|
|
|
Or suffix every `nix` command with `nix --extra-experimental-features 'nix-command flakes'`.
|
|
|
|
### Run upstream OID without modifying the source
|
|
|
|
$ nix run github:facebookexperimental/object-introspection -- --help
|
|
|
|
This will download the latest source into your Nix store along with all of its dependencies, running help afterwards.
|
|
|
|
### Build OID locally
|
|
|
|
$ git clone https://github.com/facebookexperimental/object-introspection
|
|
$ nix build
|
|
$ ./result/bin/oid --help
|
|
|
|
This will build OID from your local sources. Please note that this will NOT pick up changes to `extern/drgn` or `extern/drgn/libdrgn/velfutils`.
|
|
|
|
### Get a development environment
|
|
|
|
$ nix develop
|
|
$ cmake -B build -G Ninja -DFORCE_BOOST_STATIC=Off
|
|
$ ninja -C build
|
|
$ build/oid --help
|
|
|
|
This command provides a development shell with all the required dependencies. This is the most flexible option and will pick up source changes as CMake normally would.
|
|
|
|
Sometimes this developer environment can be polluted by things installed on your normal system. If this is an issue, use:
|
|
|
|
$ nix develop -i
|
|
|
|
This removes the environment from your host system and makes the build pure.
|
|
|
|
### Run the tests
|
|
|
|
$ nix develop
|
|
$ cmake -B build -G Ninja -DFORCE_BOOST_STATIC=Off
|
|
$ ninja -C build
|
|
$ ./tools/config_gen.py -c clang++ build/testing.oid.toml
|
|
$ ctest -j --test-dir build/test
|
|
|
|
Running tests under `nix` is new to the project and may take some time to mature. The CI is the source of truth for now.
|
|
|
|
### Format source
|
|
|
|
$ nix fmt
|
|
|
|
This formats the Nix, C++, and Python code in the repository.
|