{"id":15401609,"url":"https://github.com/andrew-wja/instrumentor","last_synced_at":"2025-08-03T15:30:57.999Z","repository":{"id":218349364,"uuid":"356222994","full_name":"andrew-wja/instrumentor","owner":"andrew-wja","description":"instrumentor is a tool for instrumenting LLVM IR to detect problems at runtime. The initial focus is on memory safety issues such as leaks, use-after-free, stack smashing, and out-of-bounds access.","archived":false,"fork":false,"pushed_at":"2021-10-21T11:00:22.000Z","size":714,"stargazers_count":4,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-25T01:13:54.967Z","etag":null,"topics":["instrumentation","llvm","memory-leak","memory-safety"],"latest_commit_sha":null,"homepage":"","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andrew-wja.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}},"created_at":"2021-04-09T10:00:11.000Z","updated_at":"2023-04-02T14:31:50.000Z","dependencies_parsed_at":"2024-01-21T12:27:48.069Z","dependency_job_id":"1620ec24-7331-4848-af44-bcfde9199285","html_url":"https://github.com/andrew-wja/instrumentor","commit_stats":null,"previous_names":["andrew-wja/instrumentor"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrew-wja%2Finstrumentor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrew-wja%2Finstrumentor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrew-wja%2Finstrumentor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrew-wja%2Finstrumentor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrew-wja","download_url":"https://codeload.github.com/andrew-wja/instrumentor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228549628,"owners_count":17935379,"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":["instrumentation","llvm","memory-leak","memory-safety"],"created_at":"2024-10-01T15:58:45.473Z","updated_at":"2024-12-07T02:21:25.128Z","avatar_url":"https://github.com/andrew-wja.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# instrumentor\n\nA tool for instrumenting LLVM IR and bitcode\n\n## Getting set up\n\n`instrumentor` uses a local build of LLVM for ease of deployment.\n\nA `Makefile` is provided to build `instrumentor` and dependencies. Just say\n`make` in the top level of the repository.\n\n## Using `instrumentor`\n\nIf you followed the build instructions above, you will have built the\n`instrumentor` executable at `dist/instrumentor` and the runtimes at\n`dist/runtimes/release`.\n\n### Modifying Your Build\n\nModifying your build to include instrumentation with `instrumentor` is\nrelatively straightforward, but of course will depend on the complexity of the\nbuild you begin with. If you are using something like the traditional separate\ncompilation workflow, integrating `instrumentor` into your build should be quite\nstraightforward.\n\nAssuming you have a build rule for object files which looks something like\nthis:\n\n```\n%.o: %.c\n    clang -c -o $@ $\u003c $(CFLAGS)\n```\n\nThen to integrate `instrumentor` you would split the production of the object\nfiles into two parts to accomodate the instrumentation step as follows:\n\n```\n# compile\n%.bc: %.c\n    clang -emit-llvm -c -o $@ $\u003c $(CFLAGS)\n\n# instrument\n%.instrumented.bc: %.bc\n    cp $\u003c $@\n    instrumentor \u003coptions\u003e $@\n\n# link\n%.o: %.instrumented.bc\n    clang -fuse-ld=lld -flto \u003cruntime\u003e.a $\u003c -o $@\n```\n\nIf you do not wish to install the runtimes and headers shipped with\n`instrumentor` on your system's include path, you can use environment variables\nsuch as `LD_LIBRARY_PATH` to temporarily extend search paths at build time.\nExamples of how to do this can be found in the `test` directory, which uses\nseparate compilation to build the test programs and their instrumented\nversions. If you have not installed the runtime shared libraries system-wide,\nyou need to ensure that the dynamic linker can find them in\n`dist/runtimes/{release,debug}` when your executable is launched.\n\n### Runtime Selection\n\nThe `instrumentor` runtimes are simple shared libraries which implement the\nbook-keeping required to check various properties of the program at runtime.\nSince the tool generates calls to these runtime functions when instrumenting\nyour program, you will need to link your final executable with one of the\nruntime libraries in order to actually execute the instrumented version of your\ncode.\n\n`instrumentor` provides different versions of each runtime depending on what\nyou would like to accomplish. If you want full checking of your program, you\nwill need to link the `_full.a` version of the runtime you wish to use.\n\nIf you want to benchmark the performance of `instrumentor`, you can link\nagainst the `_bench.a` version of the runtime. This version does everything\nthat the full version of the runtime does except that the checks which detect\nerrors always succeed, so that no errors are reported. For benchmarking\npurposes, this is useful if you are trying to compare `instrumentor` to another\ntool that allows a program to continue execution even after errors are\ndetected.\n\nIf you would like to use a dry-run approach as a placeholder while you are\nworking on integrating `instrumentor` with your build, you can use the\n`_nochecks.a` version of the runtime, which as the name suggests, does not\nactually perform any checks, and as such, will not change the behaviour of your\nprogram at execution time.\n\n## Modifying and Extending `instrumentor`\n\n### Building `instrumentor` manually\n\nSince we are using a local build of LLVM, you will either need to modify\n`$PATH` and `$LD_LIBRARY_PATH` permanently or prefix your shell commands, for\nexample:\n\n```\nLD_LIBRARY_PATH=$(realpath ./llvm-root/lib) PATH=$(realpath ./llvm-root/bin):$PATH stack build\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrew-wja%2Finstrumentor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrew-wja%2Finstrumentor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrew-wja%2Finstrumentor/lists"}