{"id":16812081,"url":"https://github.com/royjacobson/externis","last_synced_at":"2025-04-11T01:42:47.417Z","repository":{"id":58725408,"uuid":"454920814","full_name":"royjacobson/externis","owner":"royjacobson","description":"Generate profiling traces for GCC","archived":false,"fork":false,"pushed_at":"2025-03-06T09:50:57.000Z","size":158,"stargazers_count":54,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-24T22:51:15.563Z","etag":null,"topics":["cpp","flamegraph","gcc-complier","profiling"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/royjacobson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-02T20:14:03.000Z","updated_at":"2025-03-24T14:34:03.000Z","dependencies_parsed_at":"2024-10-13T10:20:41.406Z","dependency_job_id":"47b614e6-eca2-4ee5-84b2-208028a3e02a","html_url":"https://github.com/royjacobson/externis","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/royjacobson%2Fexternis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/royjacobson%2Fexternis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/royjacobson%2Fexternis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/royjacobson%2Fexternis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/royjacobson","download_url":"https://codeload.github.com/royjacobson/externis/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248327624,"owners_count":21085255,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp","flamegraph","gcc-complier","profiling"],"created_at":"2024-10-13T10:20:37.026Z","updated_at":"2025-04-11T01:42:47.406Z","avatar_url":"https://github.com/royjacobson.png","language":"C++","readme":"# Externis\n\n## What is Externis?\n\nExternis is a GCC plugin that generates profiling traces of the compilation\nprocess. The traces are viewable as a flame chart. It is inspired by clang's\n`-ftime-trace` feature.\n\nThe trace files generated by Externis are in the standard\n[trace event format](https://profilerpedia.markhansen.co.nz/formats/trace-event-format/).\nThey may be viewed in Google's [Perfetto UI](https://ui.perfetto.dev) or in\nsimilar visualization tools.\n\n## Example\n\nThis image shows a trace file made by compiling a test from `boost::geometry`.\nThe trace is viewed through Perfetto UI. You can download this example trace\n[here](./docs/example_trace.json) and play with it yourself.\n\n![Example Flame Chart from compiling a test in boost::geometry](./docs/example_chart.png)\n\nYou will notice the larger blocks at the start. This is the time the compiler\nspends on pre-processing the needed headers. After that, there's a long time\nwhere the compiler spends time compiling each individual function, but each\nfunction itself doesn't take very long. At the end there are few large blocks\nthat are the optimization passes, executed one-by-one on the whole translation\nunit.\n\nEvents shorter than 1ms are filtered out and not written to the trace, to save\non disk space.\n\n## Building\n\nThe requirements for building Externis are:\n 1. **A GCC compiler supporting C++20.** This plugin is tested with GCC11, but older\n    versions might work as well.\n 2. **The GCC plugin headers.** If you're using the GCC provided by your OS' package\n    manager there's usually a package named `gcc-plugin-devel` or something\n    similar to get the GCC plugin headers installed.\n 3. **CMake** (but barely).\n\nAfter downloading the source code, you can build and install the plugin into\nGCC's plugin directory with\n\n```bash\nmkdir build \u0026\u0026 cd build\ncmake ..\nmake externis\nsudo make install\n```\n\nPrebuilt binaries may be provided in the future.\n\n### Cross-Compilation\n\nBy default, the externis build will execute\n`${CMAKE_CXX_COMPILER} -print-file-name=plugin` to determine the location of\nthe gcc plugin header and plugin install location. If you plan to use externis\nwith the compiler that you use to build externis, this works just fine; however,\nif you want to build externis for use with a different `g++` (for example,\n`g++-arm-none-eabi`), this will not work.\n\nTo build externis for use with some other `g++`, find the plugin dir for that\ngcc (You can run `g++-arm-none-eabi -print-file-name=plugin` yourself), and\nconfigure externis with `-DEXTERNIS_GCC_PLUGIN_DIR=[that path]`, or for\nshorthand, use\n`cmake -DEXTERNIS_GCC_PLUGIN_DIR=$([your g++] -print-file-name=plugin)`. When\ndoing this, it will likely also be necessary to use `-DEXTERNIS_BUILD_TEST=OFF`\nto disable the build test validates externis.\n\n## Usage\n\nAfter building the plugin, you can use it by passing the following additional\narguments to GCC:\n```bash\n# If it's install to GCC's plugin folder\ngcc \u003cregular arguments\u003e -fplugin=externis -fplugin-arg-externis-trace=SOME_PATH/trace.json\n# Otherwise:\ngcc \u003cregular arguments\u003e -fplugin=/PATH/TO/build/externis.so -fplugin-arg-externis-trace=SOME_PATH/trace.json\n```\nAlternatively, you can specify a directory to write the files to:\n```bash\ngcc \u003cregular arguments\u003e -fplugin=/PATH/TO/build/externis.so -fplugin-arg-externis-trace-dir=SOME_PATH/\n```\nIn which case the output will be written to SOME_PATH/trace_XXXXXX.json\nIf a trace output path or directory is not given, a temporary file with the name\n`/tmp/trace_XXXXXX.json` will be used instead.\n\n## License \u0026 Copyright\n\nThis plugin was written by Roy Jacobson and is released under the GPLv3 license.\n\nThe example trace file is a derived work of boost and provided under the [Boost\nSoftware License](./docs/boost_license.txt).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froyjacobson%2Fexternis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froyjacobson%2Fexternis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froyjacobson%2Fexternis/lists"}