{"id":13648317,"url":"https://github.com/travitch/whole-program-llvm","last_synced_at":"2025-05-15T03:05:20.168Z","repository":{"id":1583188,"uuid":"1988041","full_name":"travitch/whole-program-llvm","owner":"travitch","description":"A wrapper script to build whole-program LLVM bitcode files","archived":false,"fork":false,"pushed_at":"2024-12-11T12:41:09.000Z","size":833,"stargazers_count":710,"open_issues_count":5,"forks_count":131,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-05-15T03:05:13.995Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/travitch.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":"2011-07-02T15:44:44.000Z","updated_at":"2025-05-12T10:37:17.000Z","dependencies_parsed_at":"2024-11-09T22:32:16.939Z","dependency_job_id":"43f2f3b8-c88e-4eab-9e15-29aa7ac99360","html_url":"https://github.com/travitch/whole-program-llvm","commit_stats":{"total_commits":401,"total_committers":27,"mean_commits":"14.851851851851851","dds":0.2668329177057357,"last_synced_commit":"65b14d7f50ae5777194191688dfcedf09228e53c"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travitch%2Fwhole-program-llvm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travitch%2Fwhole-program-llvm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travitch%2Fwhole-program-llvm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travitch%2Fwhole-program-llvm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/travitch","download_url":"https://codeload.github.com/travitch/whole-program-llvm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254264765,"owners_count":22041793,"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":[],"created_at":"2024-08-02T01:04:08.354Z","updated_at":"2025-05-15T03:05:20.150Z","avatar_url":"https://github.com/travitch.png","language":"Python","funding_links":[],"categories":["Python","Starchart"],"sub_categories":[],"readme":"![WLLVM](img/dragon128x128.png?raw_true)Whole Program LLVM\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blueviolet.svg)](https://opensource.org/licenses/MIT)\n[![PyPI version](https://badge.fury.io/py/wllvm.svg)](https://badge.fury.io/py/wllvm)\n[![Build Status](https://travis-ci.org/SRI-CSL/whole-program-llvm.svg?branch=master)](https://travis-ci.org/SRI-CSL/whole-program-llvm)\n[![PyPI Statistics](https://img.shields.io/pypi/dm/wllvm.svg)](https://pypistats.org/packages/wllvm)\n\n\nIntroduction\n------------\n\nThis project, WLLVM, provides tools for building whole-program (or\nwhole-library) LLVM bitcode files from an unmodified C or C++\nsource package. It currently runs on `*nix` platforms such as Linux,\nFreeBSD, and Mac OS X.\n\nWLLVM provides python-based compiler wrappers that work in two\nsteps. The wrappers first invoke the compiler as normal. Then, for\neach object file, they call a bitcode compiler to produce LLVM\nbitcode. The wrappers also store the location of the generated bitcode\nfile in a dedicated section of the object file.  When object files are\nlinked together, the contents of the dedicated sections are\nconcatenated (so we don't lose the locations of any of the constituent\nbitcode files). After the build completes, one can use a WLLVM\nutility to read the contents of the dedicated section and link all of\nthe bitcode into a single whole-program bitcode file. This utility\nworks for both executable and native libraries.\n\nThis two-phase build process is necessary to be a drop-in replacement\nfor gcc or g++ in any build system.  Using the LTO framework in gcc\nand the gold linker plugin works in many cases, but fails in the\npresence of static libraries in builds.  WLLVM's approach has the\ndistinct advantage of generating working binaries, in case some part\nof a build process requires that.\n\nWLLVM works with either clang or the gcc dragonegg plugin. If you are not interested in dragonegg support,\nand speed is an issue for you, you may want to try out [gllvm.](https://github.com/SRI-CSL/gllvm)\n\nInstallation\n------------\n\nAs of August 2016 WLLVM is now a pip package. You can just do:\n\n    pip install wllvm\n\nor\n\n    sudo pip install wllvm\n\ndepending on your machine's permissions.\n\n\nTutorial\n=======\nIf you want to develop or use the development version:\n\n```\ngit clone https://github.com/travitch/whole-program-llvm\ncd whole-program-llvm\n```\n\nNow you need to install WLLVM. You can either install\nglobally on your system in develop mode:\n\n```\nsudo pip install -e .\n```\n\nor install WLLVM into a virtual python environment\nin develop mode to avoid installing globally:\n\n```\nvirtualenv venv\nsource venv/bin/activate\npip install -e .\n```\n\n\n\nUsage\n-----\n\nWLLVM includes four python executables: `wllvm` for compiling C code\nand `wllvm++` for compiling C++, an auxiliary tool `extract-bc` for\nextracting the bitcode from a build product (object file, executable, library\nor archive), and a sanity checker, `wllvm-sanity-checker` for detecting\nconfiguration oversights.\n\nThree environment variables must be set to use these wrappers:\n\n * `LLVM_COMPILER` should be set to either `dragonegg` or `clang`.\n * `LLVM_GCC_PREFIX` should be set to the prefix for the version of gcc that should\n   be used with dragonegg.  This can be empty if there is no prefix.  This variable is\n   not used if `$LLVM_COMPILER == clang`.\n * `LLVM_DRAGONEGG_PLUGIN` should be the full path to the dragonegg plugin.  This\n   variable is not used if `$LLVM_COMPILER == clang`.\n\nOnce the environment is set up, just use `wllvm` and `wllvm++` as your C\nand C++ compilers, respectively.\n\n\nIn addition to the above environment variables the following can be optionally used:\n\n * `LLVM_CC_NAME` can be set if your clang compiler is not called `clang` but\n    something like `clang-3.7`. Similarly `LLVM_CXX_NAME` can be used to describe\n    what the C++ compiler is called. Note that in these sorts of cases, the environment\n    variable `LLVM_COMPILER` should still be set to `clang` not `clang-3.7` etc.\n    We also pay attention to the environment variables `LLVM_LINK_NAME` and `LLVM_AR_NAME` in an\n    analagous way,  since they too get adorned with suffixes in various Linux distributions.\n\n * `LLVM_COMPILER_PATH` can be set to the absolute path to the folder that\n   contains the compiler and other LLVM tools such as `llvm-link` to be used.\n   This prevents searching for the compiler in your PATH environment variable.\n   This can be useful if you have different versions of clang on your system\n   and you want to easily switch compilers without tinkering with your PATH\n   variable.\n   Example `LLVM_COMPILER_PATH=/home/user/llvm_and_clang/Debug+Asserts/bin`.\n\n* `WLLVM_CONFIGURE_ONLY` can be set to anything. If it is set, `wllvm`\n   and `wllvm++` behave like a normal C or C++ compiler. They do not\n   produce bitcode.  Setting `WLLVM_CONFIGURE_ONLY` may prevent\n   configuration errors caused by the unexpected production of hidden\n   bitcode files. It is sometimes required when configuring a build.\n\n\n\n\n\nBuilding a bitcode module with clang\n------------------------------------\n\n    export LLVM_COMPILER=clang\n\n    tar xf pkg-config-0.26.tar.gz\n    cd pkg-config-0.26\n    CC=wllvm ./configure\n    make\n\nThis should produce the executable `pkg-config`. To extract the bitcode:\n\n    extract-bc pkg-config\n\nwhich will produce the bitcode module `pkg-config.bc`.\n\n\nTutorials\n---------\n\nA gentler set of instructions on building apache in a vagrant Ubuntu 14.04 can be found\n[here,](doc/tutorial.md) and for Ubuntu 16.04 [here.](doc/tutorial-ubuntu-16.04.md)\n\nBuilding a bitcode module with dragonegg\n----------------------------------------\n\n    export LLVM_COMPILER=dragonegg\n    export LLVM_GCC_PREFIX=llvm-\n    export LLVM_DRAGONEGG_PLUGIN=/unsup/llvm-2.9/lib/dragonegg.so\n\n    tar xf pkg-config-0.26.tar.gz\n    cd pkg-config-0.26\n    CC=wllvm ./configure\n    make\n\nAgain, this should produce the executable `pkg-config`. To extract the bitcode:\n\n    extract-bc pkg-config\n\nwhich will produce the bitcode module `pkg-config.bc`.\n\n\nBuilding bitcode archive\n------------------------\n\n    export LLVM_COMPILER=clang\n    tar -xvf bullet-2.81-rev2613.tgz\n    mkdir bullet-bin\n    cd bullet-bin\n    CC=wllvm CXX=wllvm++ cmake ../bullet-2.81-rev2613/\n    make\n\n    # Produces src/LinearMath/libLinearMath.bca\n    extract-bc src/LinearMath/libLinearMath.a\n\nNote that by default extracting bitcode from an archive produces\nan archive of bitcode. You can also extract the bitcode directly into a module.\n\n    extract-bc -b src/LinearMath/libLinearMath.a\n\nproduces `src/LinearMath/libLinearMath.a.bc`.\n\n\n\nBuilding an Operating System\n----------------------------\n\nTo see how to build freeBSD 10.0 from scratch check out this\n[guide.](doc/tutorial-freeBSD.md)\n\n\nConfiguring without building bitcode\n------------------------------------\n\nSometimes it is necessary to disable the production of bitcode.\nTypically this is during configuration, where the production\nof unexpected files can confuse the configure script. For this\nwe have a flag `WLLVM_CONFIGURE_ONLY` which can be used as\nfollows:\n\n    WLLVM_CONFIGURE_ONLY=1 CC=wllvm ./configure\n    CC=wllvm make\n\n\nBuilding a bitcode archive then extracting the bitcode\n------------------------------------------------------\n\n    export LLVM_COMPILER=clang\n    tar xvfz jansson-2.7.tar.gz\n    cd jansson-2.7\n    CC=wllvm ./configure\n    make\n    mkdir bitcode\n    cp src/.libs/libjansson.a bitcode\n    cd bitcode\n    extract-bc libjansson.a\n    llvm-ar x libjansson.bca\n    ls -la\n\n\nPreserving bitcode files in a store\n--------------------------------\n\nSometimes it can be useful to preserve the bitcode files produced in a\nbuild, either to prevent deletion or to retrieve it later. If the\nenvironment variable `WLLVM_BC_STORE` is set to the absolute path of\nan existing directory,\nthen WLLVM will copy the produced bitcode file into that directory.\nThe name of the copied bitcode file is the hash of the path to the\noriginal bitcode file.  For convenience, when using both the manifest\nfeature of `extract-bc` and the store, the manifest will contain both\nthe original path, and the store path.\n\nCross-Compilation\n-----------------\n\nTo support cross-compilation WLLVM supports the `-target` triple used by clang.\nMore information can be found\n[here.](https://clang.llvm.org/docs/CrossCompilation.html#target-triple)\n\nAdditionally, WLLVM leverages `objcopy` for some of its heavy lifting. When\ncross-compiling you must ensure to use the appropriate `objcopy` for the target\narchitecture. The `BINUTILS_TARGET_PREFIX` environment variable can be used to\nset the objcopy of choice, for example, `arm-linux-gnueabihf`.\n\nLTO Support\n-----------\n\nIn some situations it is desirable to pass certain flags to clang in the step that\nproduces the bitcode. This can be fulfilled by setting the\n`LLVM_BITCODE_GENERATION_FLAGS` environment variable to the desired\nflags, for example `\"-flto -fwhole-program-vtables\"`.\n\nDebugging\n---------\n\nThe WLLVM tools can show various levels of output to aid with debugging.\nTo show this output set the `WLLVM_OUTPUT_LEVEL` environment\nvariable to one of the following levels:\n\n * `ERROR`\n * `WARNING`\n * `INFO`\n * `DEBUG`\n\nFor example:\n```\n    export WLLVM_OUTPUT_LEVEL=DEBUG\n```\nOutput will be directed to the standard error stream, unless you specify the\npath of a logfile via the `WLLVM_OUTPUT_FILE` environment variable.\n\nFor example:\n```\n    export WLLVM_OUTPUT_FILE=/tmp/wllvm.log\n```\n\n\nSanity Checking\n---------------\n\nToo many environment variables? Try doing a sanity check:\n\n```\nwllvm-sanity-checker\n```\nit might point out what is wrong.\n\n\nLicense\n-------\n\nWLLVM is released under the MIT license. See the file `LICENSE` for [details.](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftravitch%2Fwhole-program-llvm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftravitch%2Fwhole-program-llvm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftravitch%2Fwhole-program-llvm/lists"}