[ { "path": ".ci/Dockerfile.static", "content": "FROM ubuntu:20.04\n\nARG BOOST_VERSION=1_68_0\n\nSHELL [\"/bin/bash\", \"-c\"]\n\n# Install apt packages\nRUN export DEBIAN_FRONTEND=noninteractive\nRUN ln -fs /usr/share/zoneinfo/America/New_York /etc/localtime\nRUN apt-get -y update && \\\n apt-get -y install \\\n autoconf \\\n build-essential \\\n clang \\\n clang-format \\\n cmake \\\n curl \\\n git \\\n libprotobuf-dev \\\n libprotoc-dev \\\n libtool \\\n protobuf-compiler \\\n unzip \\\n wget \\\n software-properties-common\nRUN TARBALL=boost_${BOOST_VERSION}.tar.bz2 && \\\n curl -L https://archives.boost.io/release/1.68.0/source/${TARBALL} \\\n -o /tmp/${TARBALL} --fail && \\\n tar xf /tmp/${TARBALL} --one-top-level=/tmp && \\\n cd /tmp/boost_${BOOST_VERSION} && \\\n ./bootstrap.sh --prefix=/usr/local && \\\n ./b2 include=/usr/include/python3.8 link=static install && \\\n cd / && \\\n rm -rf /tmp/${TARBALL} /tmp/boost_${BOOST_VERSION}\n" }, { "path": ".ci/Dockerfile.ubuntu20", "content": "FROM ubuntu:20.04\n\n# Install apt packages\nENV VIRTUAL_ENV=/opt/venv\nENV PATH=\"$VIRTUAL_ENV/bin:$PATH\"\nRUN apt-get -y update && \\\n DEBIAN_FRONTEND=noninteractive \\\n apt-get -y install \\\n autoconf \\\n build-essential \\\n clang \\\n clang-format \\\n cmake \\\n curl \\\n default-jdk \\\n doxygen \\\n elpa-paredit \\\n emacs-nox \\\n git \\\n graphviz \\\n libprotobuf-dev \\\n libprotoc-dev \\\n libtool \\\n libboost-dev \\\n maven \\\n protobuf-compiler \\\n python3 \\\n python3-pip \\\n python3-setuptools \\\n python3-venv \\\n wget \\\n software-properties-common \\\n sbcl \\\n slime && \\\n python3 -m venv $VIRTUAL_ENV && \\\n python3 -m pip install --upgrade pip\n\n# The default version of maven from the ubuntu repositories contains a bug that\n# causes warnings about illegal reflective accesses. The build on apache's\n# website fixes this bug, so we use that build instead.\nRUN wget https://archive.apache.org/dist/maven/maven-3/3.9.3/binaries/apache-maven-3.9.3-bin.tar.gz -P /tmp\nRUN tar xf /tmp/apache-maven-*.tar.gz -C /opt\nRUN update-alternatives --install /usr/bin/mvn mvn /opt/apache-maven-3.9.3/bin/mvn 392\n\n# Install python dependencies\nCOPY python/requirements-dev.txt /tmp/requirements-dev.txt\nRUN pip3 install -r /tmp/requirements-dev.txt\n" }, { "path": ".ci/Dockerfile.ubuntu22", "content": "FROM ubuntu:22.04\n\nENV VIRTUAL_ENV=/opt/venv\nENV PATH=\"$VIRTUAL_ENV/bin:$PATH\"\nRUN apt-get -y update && \\\n DEBIAN_FRONTEND=noninteractive \\\n apt-get -y install \\\n autoconf \\\n build-essential \\\n clang \\\n clang-format \\\n cmake \\\n curl \\\n default-jdk \\\n doxygen \\\n elpa-paredit \\\n emacs-nox \\\n git \\\n graphviz \\\n libprotobuf-dev \\\n libprotoc-dev \\\n libtool \\\n libboost-dev \\\n maven \\\n protobuf-compiler \\\n python3 \\\n python3-pip \\\n python3-setuptools \\\n python3-venv \\\n wget \\\n software-properties-common \\\n sbcl \\\n slime && \\\n python3 -m venv $VIRTUAL_ENV && \\\n python3 -m pip install --upgrade pip\n\nCOPY python/requirements-dev.txt /tmp/requirements-dev.txt\nRUN pip3 install -r /tmp/requirements-dev.txt\n" }, { "path": ".ci/Dockerfile.ubuntu24", "content": "FROM ubuntu:24.04\n\nENV VIRTUAL_ENV=/opt/venv\nENV PATH=\"$VIRTUAL_ENV/bin:$PATH\"\nRUN apt-get -y update && \\\n DEBIAN_FRONTEND=noninteractive \\\n apt-get -y install \\\n autoconf \\\n build-essential \\\n clang \\\n clang-format \\\n cmake \\\n curl \\\n default-jdk \\\n doxygen \\\n elpa-paredit \\\n emacs-nox \\\n git \\\n graphviz \\\n libprotobuf-dev \\\n libprotoc-dev \\\n libtool \\\n libboost-dev \\\n # As of 24.04.1 LTS, the clang package depends on libstdc++-13-dev but\n # appears to be compiled for libstdc++-14-dev, which we need to install\n # explicitly here.\n libstdc++-14-dev \\\n maven \\\n protobuf-compiler \\\n python3 \\\n python3-pip \\\n python3-setuptools \\\n python3-venv \\\n wget \\\n software-properties-common \\\n sbcl \\\n slime && \\\n python3 -m venv $VIRTUAL_ENV && \\\n python3 -m pip install --upgrade pip\n\nCOPY python/requirements-dev.txt /tmp/requirements-dev.txt\nRUN pip3 install -r /tmp/requirements-dev.txt\n" }, { "path": ".ci/PKGBUILD", "content": "# Contributor: Eric Schulte \n# Maintainer: Eric Schulte \n_srcname=gtirb\npkgname=gtirb-git\npkgver=v1.4.7.r0.gb3094954\npkgrel=1\npkgdesc=\"GrammaTech Intermediate Representation for Binaries\"\narch=('x86_64')\nurl=\"https://github.com/grammatech/gtirb\"\nlicense=('MIT')\ndepends=('protobuf' 'python-networkx')\nmakedepends=('git' 'cmake' 'python' 'doxygen' 'graphviz' 'boost')\nprovides=('gtirb')\nsource=('git://github.com/grammatech/gtirb.git')\nsha512sums=('SKIP')\n\npkgver() {\n cd \"$_srcname\"\n git describe --long --tags --exclude \"gt/*\" | sed 's/\\([^-]*-g\\)/r\\1/;s/[-:/ ]/./g'\n}\n\nbuild() {\n cd \"$_srcname/\"\n cmake . -Bbuild -DCMAKE_INSTALL_PREFIX=/usr -DGTIRB_CL_API=OFF \\\n -DCMAKE_BUILD_TYPE=${BUILD_TYPE-RelWithDebInfo} \\\n -DCMAKE_CXX_COMPILER=${COMPILER-g++}\n cmake --build build --target all doc\n}\n\npackage() {\n cd \"$_srcname/\"\n make -Cbuild DESTDIR=\"$pkgdir\" install\n mkdir -p \"$pkgdir\"/usr/share/doc/$_srcname\n cp -R build/doc/html/ \"$pkgdir\"/usr/share/doc/$_srcname\n}\n" }, { "path": ".ci/adjust-coverage-paths.py", "content": "#!/usr/bin/env python3\n\nimport os\nfrom argparse import ArgumentParser\nfrom pathlib import Path\nfrom xml.etree import ElementTree\n\nparser = ArgumentParser(\n description=\"\"\"\n Adjusts the source paths in coverage.xml to satisfy GitLab's expectations.\n Specifically, it removes the build tree prefix from the sources and\n replaces it with the source tree prefix. These prefixes are determined via\n command-line arguments or CI environment variables.\n \"\"\"\n)\nparser.add_argument(\n \"coverage\",\n metavar=\"coverage.xml\",\n type=Path,\n help=\"path of cobertura coverage file to fix\",\n)\ngroup = parser.add_mutually_exclusive_group(required=True)\ngroup.add_argument(\n \"-i\", \"--in-place\", action=\"store_true\", help=\"rewrite coverage in place\"\n)\ngroup.add_argument(\n \"-o\", \"--output\", metavar=\"file\", help=\"write modified coverage to file\"\n)\nparser.add_argument(\n \"--source-dir\",\n metavar=\"path\",\n default=os.environ.get(\"CI_PROJECT_DIR\"),\n help=\"root of the GTIRB repository\",\n)\nparser.add_argument(\n \"--build-dir\",\n metavar=\"path\",\n type=Path,\n help=\"path where coverage was run (default coverage.xml parent directory)\",\n)\nargs = parser.parse_args()\n\nif args.source_dir is None:\n parser.error(\"either --source-dir or CI_PROJECT_DIR is required\")\nargs.source_dir = Path(args.source_dir).resolve()\n\nif args.build_dir is None:\n args.build_dir = args.coverage.parent\nargs.build_dir = args.build_dir.resolve()\n\net = ElementTree.parse(args.coverage)\nfor source in et.iter(\"source\"):\n if source.text:\n relpath = Path(source.text).relative_to(args.build_dir)\n fixed = str(Path(args.source_dir, relpath))\n print(\"mapping\", source.text, \"to\", fixed)\n source.text = fixed\n\nif args.output:\n et.write(args.output)\nelse:\n et.write(args.coverage)\n" }, { "path": ".ci/build.py", "content": "#!/usr/bin/env python\nimport subprocess\nimport sys\n\nimport conanfile\n\n\ndef run_conan(args):\n cmd = [\"conan\"] + args\n print(\"running: %s\" % \" \".join(cmd))\n sys.stdout.flush()\n subprocess.check_call(cmd)\n\n\ndef build(argv):\n props = conanfile.Properties()\n run_conan([\"create\", \".\", props.conan_ref] + argv)\n archived_channels = props.archived_channels\n if props.conan_channel in archived_channels:\n run_conan(\n [\"upload\", props.conan_recipe, \"--all\", \"--remote\", \"gitlab\"]\n )\n else:\n print(\n \"Conan channel not archived. Update archived_branches in \"\n \"conanfile.py to get archival.\"\n )\n print(\"archived channels: \")\n print(*archived_channels, sep=\", \")\n print(\"channel built: \" + props.conan_channel)\n\n\nif __name__ == \"__main__\":\n build(sys.argv[1:])\n" }, { "path": ".ci/gitlab-ci.yml", "content": "variables:\n # The IMAGE_TAG is derived from the branch name so that if a branch modifies\n # the CI images, it builds and runs using the new images without conflicting\n # with master.\n IMAGE_TAG: \"$CI_COMMIT_REF_SLUG\"\n GIT_SUBMODULE_STRATEGY: recursive\n EXTRA_INDEX_URL: https://__token__:$GL_PKG_API_TOKEN@git.grammatech.com/api/v4/projects/1587/packages/pypi/simple\n # The follow two variables are used by the package-uploader.\n PROJECT_ID: $CI_PROJECT_ID\n PIPELINE_ID: $CI_PIPELINE_ID\n CONAN_PASSWORD: $CI_JOB_TOKEN\n CONAN_VERSION: \"1.59\"\n # Limit build parallelism to avoid overwhelming CI servers.\n MAKE_JOBS: 8\n\nstages:\n - build-images\n - prebuild\n - build\n - build-installers\n - test-setup\n - test-packages1\n - test-packages2\n - deploy\n - deploy-apt\n - upload\n\ndefault:\n tags: [shared]\n\n.build-ci-image: &build-ci-image\n stage: build-images\n image:\n name: quay.io/buildah/stable\n script:\n # Configure authentication credentials for GitLab\n - buildah login -u \"$CI_REGISTRY_USER\" -p \"$CI_REGISTRY_PASSWORD\" \"$CI_REGISTRY\"\n - buildah login -u \"$DOCKERHUB_USERNAME\" -p \"$DOCKERHUB_PASSWORD\" https://index.docker.io/v1/\n # Build our image (using a cache if available)\n - >-\n buildah build\n -f \"$CI_PROJECT_DIR/$DOCKERFILE_PATH\"\n --cache-from \"$DOCKER_REGISTRY/$CI_PROJECT_PATH/$IMAGE_NAME/cache\"\n --cache-to \"$DOCKER_REGISTRY/$CI_PROJECT_PATH/$IMAGE_NAME/cache\"\n --layers\n --tag \"$DOCKER_REGISTRY/$CI_PROJECT_PATH/$IMAGE_NAME:$IMAGE_TAG\"\n \"$CI_PROJECT_DIR\"\n # Push to our internal registry\n - buildah push \"$DOCKER_REGISTRY/$CI_PROJECT_PATH/$IMAGE_NAME:$IMAGE_TAG\"\n # If we're on the master branch, also push the latest tag.\n - >-\n if [ \"$CI_COMMIT_BRANCH\" = \"$CI_DEFAULT_BRANCH\" ]; then\n buildah push \"$DOCKER_REGISTRY/$CI_PROJECT_PATH/$IMAGE_NAME:$IMAGE_TAG\" \\\n \"$DOCKER_REGISTRY/$CI_PROJECT_PATH/$IMAGE_NAME:latest\"\n fi\n\nbuild-ci-image-ubuntu20:\n <<: *build-ci-image\n variables:\n DOCKERFILE_PATH: .ci/Dockerfile.ubuntu20\n IMAGE_NAME: ubuntu20\n\nbuild-ci-image-ubuntu22:\n <<: *build-ci-image\n variables:\n DOCKERFILE_PATH: .ci/Dockerfile.ubuntu22\n IMAGE_NAME: ubuntu22\n\nbuild-ci-image-ubuntu24:\n <<: *build-ci-image\n variables:\n DOCKERFILE_PATH: .ci/Dockerfile.ubuntu24\n IMAGE_NAME: ubuntu24\n\nbuild-ci-image-static:\n <<: *build-ci-image\n variables:\n DOCKERFILE_PATH: .ci/Dockerfile.static\n IMAGE_NAME: static\n\ncheck-format:\n stage: prebuild\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu20:$IMAGE_TAG\n script:\n - |+\n pre-commit run --all-files --show-diff-on-failure || ( (cat <\n cmake ../\n -DCMAKE_BUILD_TYPE=$BUILD_TYPE\n -DCMAKE_CXX_COMPILER=${CXX_COMPILER:-g++}\n -DCPACK_DEBIAN_PACKAGE_RELEASE=\"$(lsb_release -sc)\"\n -DENABLE_CODE_COVERAGE=${ENABLE_CODE_COVERAGE:-OFF}\n -DGTIRB_BUILD_SHARED_LIBS=${GTIRB_BUILD_SHARED_LIBS:-ON}\n -DGTIRB_PACKAGE_POLICY=$PACKAGE_POLICY\n -DGTIRB_RELEASE_VERSION=$RELEASE_VERSION\n -DGTIRB_STRIP_DEBUG_SYMBOLS=On\n -DGTIRB_CL_API=${GTIRB_CL_API:-OFF}\n -DGTIRB_CXX_API=${GTIRB_CXX_API:-OFF}\n -DGTIRB_JAVA_API=${GTIRB_JAVA_API:-OFF}\n -DGTIRB_PY_API=${GTIRB_PY_API:-OFF}\n - make -j${MAKE_JOBS}\n - ctest --output-on-failure\n\nbuild-ubuntu20-gcc:\n variables:\n IMAGE_NAME: 'ubuntu20'\n GTIRB_CXX_API: 'ON'\n CXX_COMPILER: 'g++'\n CPACK_GENERATOR: 'DEB'\n BUILD_TYPE: 'RelWithDebInfo'\n PACKAGE_POLICY: \"unix\"\n <<: *build\n\nbuild-ubuntu22-gcc:\n variables:\n IMAGE_NAME: 'ubuntu22'\n GTIRB_CXX_API: 'ON'\n CXX_COMPILER: 'g++'\n CPACK_GENERATOR: 'DEB'\n BUILD_TYPE: 'RelWithDebInfo'\n PACKAGE_POLICY: \"unix\"\n <<: *build\n\nbuild-ubuntu24-gcc:\n variables:\n IMAGE_NAME: 'ubuntu24'\n GTIRB_CXX_API: 'ON'\n CXX_COMPILER: 'g++'\n CPACK_GENERATOR: 'DEB'\n BUILD_TYPE: 'RelWithDebInfo'\n PACKAGE_POLICY: \"unix\"\n <<: *build\n\nbuild-ubuntu24-gcc-debug:\n variables:\n IMAGE_NAME: 'ubuntu24'\n GTIRB_CXX_API: 'ON'\n CXX_COMPILER: 'g++'\n BUILD_TYPE: 'Debug'\n PACKAGE_POLICY: \"unix\"\n <<: *build\n\nbuild-ubuntu24-clang-debug:\n variables:\n IMAGE_NAME: 'ubuntu24'\n GTIRB_CXX_API: 'ON'\n CXX_COMPILER: 'clang++'\n BUILD_TYPE: 'Debug'\n PACKAGE_POLICY: \"unix\"\n <<: *build\n\nbuild-static:\n variables:\n IMAGE_NAME: 'static'\n GTIRB_CXX_API: 'ON'\n CXX_COMPILER: 'g++'\n BUILD_TYPE: 'RelWithDebInfo'\n GTIRB_BUILD_SHARED_LIBS: 'OFF'\n <<: *build\n\nbuild-java:\n variables:\n IMAGE_NAME: 'ubuntu24'\n GTIRB_JAVA_API: 'ON'\n <<: *build\n\nbuild-lisp:\n variables:\n IMAGE_NAME: 'ubuntu20'\n GTIRB_CL_API: 'ON'\n <<: *build\n\nbuild-ubuntu20-python:\n variables:\n IMAGE_NAME: 'ubuntu20'\n GTIRB_PY_API: 'ON'\n <<: *build\n\nbuild-ubuntu24-python:\n variables:\n IMAGE_NAME: 'ubuntu24'\n GTIRB_PY_API: 'ON'\n <<: *build\n\ngenerate-coverage:\n variables:\n IMAGE_NAME: 'ubuntu24'\n BUILD_TYPE: 'Debug'\n CXX_COMPILER: 'g++'\n ENABLE_CODE_COVERAGE: 'ON'\n GTIRB_CXX_API: 'ON'\n GTIRB_PY_API: 'ON'\n artifacts:\n # Upload coverage reports and source for report-coverage-* jobs to use.\n paths:\n - build/**/*.gcno\n - build/**/*.gcda\n - build/python/.coverage*\n - build/**/*.py\n - build/**/*.h\n - build/**/*.cc\n - build/**/*.cpp\n before_script:\n - pip install \"gcovr>=8.6\" coverage\n <<: *build\n\n# > If there is more than one matched line in the job output, the last line is used\n# https://docs.gitlab.com/ee/ci/yaml/index.html#coverage\n# We output the two coverage numbers in separate jobs(report-coverage-*) so\n# that both can be reported to GitLab.\nreport-coverage-cpp:\n stage: build\n needs: [generate-coverage]\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu24:$IMAGE_TAG\n coverage: '/^TOTAL.*\\s+(\\d+\\%)$/'\n script:\n - pip install \"gcovr>=8.6\"\n - cd build\n - gcovr --exclude=googletest-src --exclude=doc --exclude=..*/proto --exclude=..*/test --root ..\n\nreport-coverage-py:\n stage: build\n needs: [generate-coverage]\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu24:$IMAGE_TAG\n coverage: '/^TOTAL.*\\s+(\\d+\\%)$/'\n artifacts:\n reports:\n coverage_report:\n coverage_format: cobertura\n path: build/python/coverage.xml\n script:\n - pip install -r python/requirements-dev.txt\n - cd build/python\n - tox run -e report\n - ../../.ci/adjust-coverage-paths.py --in-place coverage.xml --build-dir ..\n\n\n# The build artifact timestamps may be out-of-date relative to the newly cloned\n# repository for later jobs. These commands will update the timestamps to bring\n# them up to date without actually building much. This is significantly faster\n# than rebuilding out-of-date files in the later jobs.\n.update-artifact-timestamps: &update-artifact-timestamps\n - make -C build --touch\n\npython-wheel:\n stage: build-installers\n needs: [build-ubuntu24-python]\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu24:$IMAGE_TAG\n artifacts:\n name: \"$CI_COMMIT_REF_NAME-$CI_JOB_NAME\"\n paths:\n - gtirb-*-py*-none-any.whl\n script:\n - *update-artifact-timestamps\n - pip3 wheel --no-deps build/python\n\npython-wheel-unstable:\n stage: build-installers\n needs: [python-wheel]\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu24:$IMAGE_TAG\n rules:\n - if: '$CI_COMMIT_BRANCH == \"master\"'\n artifacts:\n name: \"$CI_COMMIT_REF_NAME-$CI_JOB_NAME\"\n paths:\n - gtirb-unstable-py3-none-any.whl\n script:\n - cp gtirb-*-py*-none-any.whl ./gtirb-unstable-py3-none-any.whl\n\ntest-capstone-example:\n stage: test-packages1\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu24:$IMAGE_TAG\n needs: ['build-ubuntu24-gcc']\n script:\n - *update-artifact-timestamps\n - cd build\n - '[[ ! -f bin/ex-jumps ]]'\n - apt-get install -y libcapstone-dev\n - cmake ..\n - make -j${MAKE_JOBS}\n - '[[ -f bin/ex-jumps ]]'\n\ntest-default-install:\n stage: test-packages1\n image: $DOCKER_REGISTRY/rewriting/gtirb/$IMAGE_NAME:$IMAGE_TAG\n variables:\n IMAGE_NAME: 'ubuntu24'\n COMPILER: 'g++-9'\n needs: ['build-ubuntu24-gcc']\n script:\n - *update-artifact-timestamps\n - make -C build install && rm -rf build\n - LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH .ci/test-install-all.sh\n\ntest-default-install-static:\n stage: test-packages1\n image: $DOCKER_REGISTRY/rewriting/gtirb/static:$IMAGE_TAG\n needs: ['build-static']\n script:\n - *update-artifact-timestamps\n - '[ -e build/lib/libgtirb.a ]'\n - '[ ! -e build/lib/libgtirb.so ]'\n - make -C build install\n - rm -rf build\n - LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH .ci/test-install-static.sh\n\ntest-install-different-prefix:\n stage: test-packages1\n image: $DOCKER_REGISTRY/rewriting/gtirb/$IMAGE_NAME:$IMAGE_TAG\n variables:\n IMAGE_NAME: 'ubuntu24'\n COMPILER: 'g++-9'\n needs: ['build-ubuntu24-gcc']\n script:\n - *update-artifact-timestamps\n - cmake . -B build -DCMAKE_INSTALL_PREFIX=/tmp/prefix\n - make -C build install\n - rm -rf build\n - >\n CPPFLAGS=-I/tmp/prefix/include\n LDFLAGS=-L/tmp/prefix/lib\n LD_LIBRARY_PATH=/tmp/prefix/lib\n .ci/test-install-all.sh\n\ntest-install-with-destdir:\n stage: test-packages1\n image: $DOCKER_REGISTRY/rewriting/gtirb/$IMAGE_NAME:$IMAGE_TAG\n variables:\n IMAGE_NAME: 'ubuntu24'\n COMPILER: 'g++-9'\n needs: ['build-ubuntu24-gcc']\n script:\n - *update-artifact-timestamps\n - DESTDIR=/tmp/destdir make -C ./build install\n - >\n CPPFLAGS=-I/tmp/destdir/usr/local/include\n LDFLAGS=-L/tmp/destdir/usr/local/lib\n LD_LIBRARY_PATH=/tmp/destdir/usr/local/lib\n .ci/test-install-all.sh\n\ntest-interop:\n stage: test-packages1\n needs: ['build-ubuntu24-gcc', 'python-wheel']\n image: ${DOCKER_REGISTRY}/rewriting/gtirb/ubuntu24:$IMAGE_TAG\n script:\n - *update-artifact-timestamps\n - pip3 install gtirb-*-py*-none-any.whl\n - .ci/test-interop.sh\n\n.conan-linux: &conan-linux\n stage: deploy\n needs: [check-format]\n image: $DOCKER_REGISTRY/rewriting/gtirb/$IMAGE_NAME:$IMAGE_TAG\n script:\n - python3 -m pip install --upgrade conan~=$CONAN_VERSION\n - conan profile new default --detect\n - conan profile update settings.compiler.libcxx=libstdc++11 default\n - conan remote add gitlab ${CI_API_V4_URL}/packages/conan\n - conan user ci_user -r gitlab -p\n - export PYTHONPATH=\"$(pwd)\"\n - python3 .ci/build.py\n\nconan-linux-gcc9:\n variables:\n IMAGE_NAME: ubuntu20\n <<: *conan-linux\n\nconan-linux-gcc11:\n variables:\n IMAGE_NAME: ubuntu22\n <<: *conan-linux\n\n.conan-windows: &conan-windows\n stage: deploy\n needs: [check-format]\n tags: [ddisasm-windows]\n artifacts:\n name: \"$CI_COMMIT_REF_NAME-$CI_JOB_NAME\"\n paths:\n - gtirb*.zip\n script:\n # Setting CI_PROJECT_DIR to $(pwd) because CI doesn't properly set CI_PROJECT_DIR with VirtualBox runners.\n - export CI_PROJECT_DIR=`cygpath -w $(pwd)`\n # Initialize\n - systeminfo\n - python -m pip install --upgrade conan~=$CONAN_VERSION\n - export PYTHONPATH=$CI_PROJECT_DIR\n # Setup Remote and Authenticate\n - conan remote add gitlab ${CI_API_V4_URL}/packages/conan\n - conan user ci_user -r gitlab -p\n # Build\n - export GTIRB_DISABLE_PARALLEL_BUILD=1\n - python .ci/build.py -s build_type=$BUILD_TYPE\n # Install\n # Python print() on Windows returns CRLF and will cause issues in CI - use \"print('string', end='')\" when outputting from python.\n - export PKG_INSTALL_NAME=`python -c \"import conanfile; print(conanfile.Properties().conan_recipe, end='')\"`\n - conan install $PKG_INSTALL_NAME -g deploy --build=missing --install-folder=\"./packages\"\n # Package\n - export PKG_NAME=`conan inspect . --raw name`\n - export PKG_VERSION=`conan inspect . --raw version`\n - export PKG_ARCH=`uname -m`\n - cd ./packages\n # Library Package\n - export PKG_FILENAME=\"${CI_PROJECT_DIR}\\\\${PKG_NAME}-${PKG_VERSION}.win10.${PKG_ARCH}.zip\"\n - export PKG_MANIFEST=(\n \"gtirb/bin/gtirb.dll\"\n \"gtirb/licenses/LICENSE.txt\"\n )\n - zip -r $PKG_FILENAME ${PKG_MANIFEST[@]}\n # Development Package\n - export PKG_FILENAME_DEV=\"${CI_PROJECT_DIR}\\\\${PKG_NAME}-dev-${PKG_VERSION}.win10.${PKG_ARCH}.zip\"\n - export PKG_MANIFEST_DEV=(\n \"${PKG_MANIFEST[@]}\"\n \"gtirb/lib/gtirb.lib\"\n \"gtirb/include/gtirb\"\n )\n - zip -r $PKG_FILENAME_DEV ${PKG_MANIFEST_DEV[@]}\n\nconan-windows-debug:\n variables:\n BUILD_TYPE: Debug\n <<: *conan-windows\n\nconan-windows-release:\n variables:\n BUILD_TYPE: Release\n <<: *conan-windows\n\nconan-windows-32:\n stage: deploy\n tags: [ddisasm-windows]\n needs: []\n variables:\n ARCHITECTURE: x64\n script:\n - systeminfo\n - export PATH=\"C:\\\\Program Files\\\\Python38;$PATH\"\n - export PYTHONPATH=\"$(cygpath -w $(pwd))\"\n # Install conan\n - python -m pip install --upgrade conan~=$CONAN_VERSION\n # Setup Remote and Authenticate\n - conan remote add gitlab ${CI_API_V4_URL}/packages/conan\n - conan user ci_user -r gitlab -p\n # The boost options disable building boost with libiconv. This is important, because we can't get the package to build with --build=libiconv.\n - CI_PROJECT_DIR=$(cygpath -w $(pwd)) python .ci/build.py -s arch=x86 -s compiler.runtime=MT --build=protobuf -o protobuf:with_zlib=False --build=gtirb --build=boost -o boost:zlib=False -o boost:bzip2=False -o boost:without_locale=True -o boost:without_log=True --build=missing\n\nexternal-pypi:\n stage: deploy\n needs: [build-ubuntu24-gcc, python-wheel]\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu24:$IMAGE_TAG\n rules:\n - if: '$CI_COMMIT_REF_NAME =~ /^release-.*/'\n script:\n - pip3 install twine wheel setuptools pkginfo --upgrade\n - pip3 install gtirb-*-py*-none-any.whl\n - GTIRB_VERSION=$(python3 -c \"import gtirb; print(gtirb.__version__)\")\n # We won't be releasing our dev packages externally, so fail if this is a\n # .dev package.\n - if [[ \"$GTIRB_VERSION\" =~ \\.dev[[:digit:]]*(\\+.*)?$ ]]; then exit 1; fi\n - twine check gtirb-*-py*-none-any.whl\n - twine upload gtirb-*-py*-none-any.whl -u __token__ -p $PYPI_API_KEY\n\n# On master, we only upload and overwrite `.dev` versions of the python\n# package. Non-.dev versions should only be uploaded on versioned\n# release-.* branches. This is so the versioning of our python packages\n# coincides with that of our conan packages, where dev packages are\n# produced from master, and stable, versioned packages are produced\n# on release-.* branches.\ninternal-pypi:\n stage: deploy\n needs: [build-ubuntu24-gcc, python-wheel]\n image: python:3.9\n rules:\n - if: '$CI_COMMIT_BRANCH == \"master\"'\n - if: '$CI_COMMIT_REF_NAME =~ /^release-.*/'\n script:\n - pip3 install twine wheel setuptools pkginfo --upgrade\n - wget https://git.grammatech.com/research/templates/python-module/raw/master/.pypirc\n - sed \"s/password = /password = $GL_PKG_API_TOKEN/\" .pypirc > ~/.pypirc\n - pip3 install gtirb-*-py*-none-any.whl\n - NEW_VERSION=$(python3 -c \"import gtirb; print(gtirb.__version__)\")\n - if [[ \"$NEW_VERSION\" =~ \\.dev[[:digit:]]*(\\+.*)?$ && \"$CI_COMMIT_REF_NAME\" =~ ^release-.* ]]; then exit 1; fi\n - if [[ \"$CI_COMMIT_BRANCH\" == \"master\" ]]; then\n if [[ ! \"$NEW_VERSION\" =~ \\.dev[[:digit:]]*$ ]]; then\n echo \"[ERROR] Only .dev versions can be uploaded from the master branch.\";\n exit 1;\n fi;\n if pip3 install --extra-index-url=$EXTRA_INDEX_URL \"gtirb>$NEW_VERSION\" 2>/dev/null; then\n echo \"[ERROR] The package version being published on master should always be >= the version in the repository.\";\n exit 1;\n fi;\n wget https://git.grammatech.com/research/templates/python-module/raw/master/delete_remote_packages.py;\n python3 delete_remote_packages.py $GL_PKG_API_TOKEN gtirb-*-py*-none-any.whl;\n fi\n - twine check gtirb-*-py*-none-any.whl\n - twine upload --verbose --repository repypi gtirb-*-py*-none-any.whl\n\n# Apt packaging related jobs\n.build-ubuntu-packages: &build-ubuntu-packages\n stage: build-installers\n artifacts:\n name: \"$CI_COMMIT_REF_NAME-$CI_JOB_NAME\"\n paths:\n - build\n script:\n - pip3 install setuptools wheel --upgrade\n - cd build\n - cpack -G \"DEB\" -D CPACK_GTIRB_PACKAGE=debian-lib;\n - cpack -G \"DEB\" -D CPACK_GTIRB_PACKAGE=debian-dev;\n - cpack -G \"DEB\" -D CPACK_GTIRB_PACKAGE=debian-debug;\n\nbuild-ubuntu20-packages:\n needs: [build-ubuntu20-gcc]\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu20:$IMAGE_TAG\n <<: *build-ubuntu-packages\n\nbuild-ubuntu22-packages:\n needs: [build-ubuntu22-gcc]\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu22:$IMAGE_TAG\n <<: *build-ubuntu-packages\n\nbuild-ubuntu24-packages:\n needs: [build-ubuntu24-gcc]\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu24:$IMAGE_TAG\n <<: *build-ubuntu-packages\n\n.setup-test-apt-repo: &setup-test-apt-repo\n stage: test-setup\n artifacts:\n name: \"$CI_COMMIT_REF_NAME-$CI_JOB_NAME\"\n paths:\n - apt-repo\n script:\n - mkdir apt-repo\n - cp build/*.deb apt-repo\n - cd apt-repo && dpkg-scanpackages . /dev/null > Packages\n\n\n.test-ubuntu-libgtirb-dev: &test-ubuntu-libgtirb-dev\n stage: test-packages1\n artifacts:\n name: \"$CI_COMMIT_REF_NAME-$CI_JOB_NAME\"\n paths:\n - test-install\n script:\n - echo -e \"\\ndeb [trusted=yes] file:$(pwd)/apt-repo ./\\n\" >> /etc/apt/sources.list\n - cat /etc/apt/sources.list\n - 'TEST_PKG_NAME=$(dpkg --info apt-repo/libgtirb-dev_*.deb | sed -n \"s/Package: //p\")'\n - apt-get update -y && apt-get install -y --allow-unauthenticated $TEST_PKG_NAME\n - cp .ci/test-install.cpp ./\n - g++ test-install.cpp -std=c++17 -o test-install -lgtirb -lstdc++\n - ./test-install\n\n.test-ubuntu-libgtirb: &test-ubuntu-libgtirb\n stage: test-packages2\n script:\n - echo -e \"\\ndeb [trusted=yes] file:$(pwd)/apt-repo ./\\n\" >> /etc/apt/sources.list\n - 'TEST_PKG_NAME=$(dpkg --info apt-repo/libgtirb_*.deb | sed -n \"s/Package: //p\")'\n - apt-get update -y && apt-get install -y --allow-unauthenticated $TEST_PKG_NAME\n - ./test-install\n\n.test-ubuntu-libgtirb-dbg: &test-ubuntu-libgtirb-dbg\n stage: test-packages1\n script:\n - echo -e \"\\ndeb [trusted=yes] file:$(pwd)/apt-repo ./\\n\" >> /etc/apt/sources.list\n - 'TEST_PKG_NAME=$(dpkg --info apt-repo/libgtirb-dbg_*.deb | sed -n \"s/Package: //p\")'\n - apt-get update -y && apt-get install -y --allow-unauthenticated $TEST_PKG_NAME\n - '[ -f /usr/lib/debug/.build-id/$(readelf -n /usr/lib/libgtirb.so | grep ''Build ID: '' | cut -d\":\" -f2 | sed -E ''s/ ([a-f0-9]{2,})([a-f0-9]{30,})/\\1\\/\\2/g'').debug ];'\n\nsetup-ubuntu20-test-apt-repo:\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu20:$IMAGE_TAG\n needs: [build-ubuntu20-packages]\n <<: *setup-test-apt-repo\n\nsetup-ubuntu22-test-apt-repo:\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu22:$IMAGE_TAG\n needs: [build-ubuntu22-packages]\n <<: *setup-test-apt-repo\n\nsetup-ubuntu24-test-apt-repo:\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu24:$IMAGE_TAG\n needs: [build-ubuntu24-packages]\n <<: *setup-test-apt-repo\n\ntest-ubuntu20-libgtirb-dev:\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu20:$IMAGE_TAG\n needs: [setup-ubuntu20-test-apt-repo]\n <<: *test-ubuntu-libgtirb-dev\n\ntest-ubuntu22-libgtirb-dev:\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu22:$IMAGE_TAG\n needs: [setup-ubuntu22-test-apt-repo]\n <<: *test-ubuntu-libgtirb-dev\n\ntest-ubuntu24-libgtirb-dev:\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu24:$IMAGE_TAG\n needs: [setup-ubuntu24-test-apt-repo]\n <<: *test-ubuntu-libgtirb-dev\n\ntest-ubuntu20-libgtirb-dbg:\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu20:$IMAGE_TAG\n needs: [setup-ubuntu20-test-apt-repo]\n <<: *test-ubuntu-libgtirb-dbg\n\ntest-ubuntu22-libgtirb-dbg:\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu22:$IMAGE_TAG\n needs: [setup-ubuntu22-test-apt-repo]\n <<: *test-ubuntu-libgtirb-dbg\n\ntest-ubuntu24-libgtirb-dbg:\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu24:$IMAGE_TAG\n needs: [setup-ubuntu24-test-apt-repo]\n <<: *test-ubuntu-libgtirb-dbg\n\ntest-ubuntu20-libgtirb:\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu20:$IMAGE_TAG\n needs: [setup-ubuntu20-test-apt-repo,test-ubuntu20-libgtirb-dev]\n <<: *test-ubuntu-libgtirb\n\ntest-ubuntu22-libgtirb:\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu22:$IMAGE_TAG\n needs: [setup-ubuntu22-test-apt-repo,test-ubuntu22-libgtirb-dev]\n <<: *test-ubuntu-libgtirb\n\ntest-ubuntu24-libgtirb:\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu24:$IMAGE_TAG\n needs: [setup-ubuntu24-test-apt-repo,test-ubuntu24-libgtirb-dev]\n <<: *test-ubuntu-libgtirb\n\n.debian-installer: &debian-installer\n stage: deploy\n artifacts:\n name: \"$CI_COMMIT_REF_NAME-$CI_JOB_NAME\"\n paths:\n - '*gtirb*.deb'\n script:\n - cp build/*gtirb*.deb ./\n\ndebian-installer-ubuntu20:\n image: $DOCKER_REGISTRY/rewriting/gtirb/ubuntu20:$IMAGE_TAG\n needs: [test-ubuntu20-libgtirb, build-ubuntu20-packages]\n <<: *debian-installer\n\n.apt-upload: &apt-upload\n stage: deploy-apt\n trigger:\n project: rewriting/utility/package-uploader\n strategy: depend\n\napt-public-ubuntu20-unstable:\n <<: *apt-upload\n rules:\n - if: '$CI_COMMIT_BRANCH == \"master\"'\n variables:\n JOB_NAME: debian-installer-ubuntu20\n APT_REPO: public\n APT_REPO_CODENAMES: focal\n APT_REPO_COMPONENT: unstable\n\napt-public-ubuntu20-stable:\n <<: *apt-upload\n rules:\n - if: '$CI_COMMIT_REF_NAME =~ /^release-.*/'\n variables:\n JOB_NAME: debian-installer-ubuntu20\n APT_REPO: public\n APT_REPO_CODENAMES: focal\n APT_REPO_COMPONENT: stable\n\napt-internal-ubuntu20-unstable:\n <<: *apt-upload\n rules:\n - if: '$CI_COMMIT_BRANCH == \"master\"'\n variables:\n JOB_NAME: debian-installer-ubuntu20\n APT_REPO: internal\n APT_REPO_CODENAMES: focal\n APT_REPO_COMPONENT: unstable\n\napt-internal-ubuntu20-stable:\n <<: *apt-upload\n rules:\n - if: '$CI_COMMIT_REF_NAME =~ /^release-.*/'\n variables:\n JOB_NAME: debian-installer-ubuntu20\n APT_REPO: internal\n APT_REPO_CODENAMES: focal\n APT_REPO_COMPONENT: stable\n\nmaven-central-upload:\n stage: deploy\n needs: [build-java]\n trigger:\n project: rewriting/utility/package-uploader\n strategy: depend\n rules:\n - if: '$CI_COMMIT_REF_NAME == \"master\"'\n - if: '$CI_COMMIT_REF_NAME =~ /^release-.*/'\n variables:\n JOB_NAME: build-java\n JAVA_POM_SUBDIR: ./build/java\n\n.windows-upload: &windows-upload\n stage: upload\n trigger:\n project: rewriting/utility/package-uploader\n strategy: depend\n needs: [conan-windows-release]\n\nwindows-upload-public:\n <<: *windows-upload\n rules:\n - if: '$CI_COMMIT_REF_NAME =~ /^release-.*/'\n - if: '$CI_COMMIT_REF_NAME == \"master\"'\n variables:\n JOB_NAME: conan-windows-release\n FILESERVER: public\n FILESERVER_SUBDIR_NAME: windows-release\n\nwindows-upload-internal:\n <<: *windows-upload\n rules:\n - if: '$CI_COMMIT_REF_NAME =~ /^release-.*/'\n - if: '$CI_COMMIT_REF_NAME == \"master\"'\n variables:\n JOB_NAME: conan-windows-release\n FILESERVER: internal\n FILESERVER_SUBDIR_NAME: windows-release\n\nwheel-upload-public:\n stage: upload\n trigger:\n project: rewriting/utility/package-uploader\n strategy: depend\n needs: [python-wheel-unstable]\n rules:\n - if: '$CI_COMMIT_REF_NAME == \"master\"'\n variables:\n JOB_NAME: python-wheel-unstable\n FILESERVER: public\n FILESERVER_SUBDIR_NAME: python\n" }, { "path": ".ci/pre-commit", "content": "#!/bin/bash\nOUTPUT=$(git clang-format --diff)\nif [ \"${OUTPUT}\" == \"no modified files to format\" ] ||\n [ \"${OUTPUT}\" == \"clang-format did not modify any files\" ];then\n exit 0\nelse\n echo \"Run git clang-format, then commit.\"\n exit 1\nfi\n" }, { "path": ".ci/test-install-all.sh", "content": "#!/bin/sh -e\n\nset -o xtrace\nset -o nounset\nset -o errexit\n\nbuilddir=$(pwd)\nworkdir=`mktemp -d`\ntrap 'cd / ; rm -rf $workdir' EXIT\ncd $workdir\n\n# Compile and run a C++ file that links to libgtirb\ncp $builddir/.ci/test-install.cpp ./\nmake CXXFLAGS=-std=c++17 LDLIBS=-lgtirb test-install\n./test-install\n" }, { "path": ".ci/test-install-static.sh", "content": "#!/bin/sh -e\n\nset -o xtrace\nset -o nounset\nset -o errexit\n\nbuilddir=$(pwd)\nworkdir=`mktemp -d`\ntrap 'cd / ; rm -rf $workdir' EXIT\ncd $workdir\n\n# Compile and run a C++ file that links to libgtirb statically\ncp $builddir/.ci/test-install.cpp ./\nmake 'CXXFLAGS=-std=c++17' 'LDLIBS=-lgtirb -lgtirb_proto -lprotobuf -lpthread' test-install\n./test-install\n" }, { "path": ".ci/test-install.cpp", "content": "#include \n#include \n#include \n\nint main() {\n auto filename = std::tmpnam(nullptr);\n std::ofstream ofs{filename, std::ios_base::binary};\n auto ctx1 = gtirb::Context();\n auto ir1 = gtirb::IR::Create(ctx1);\n ir1->save(ofs);\n ofs.close();\n std::ifstream ifs{filename, std::ios_base::binary};\n auto ctx2 = gtirb::Context();\n if (auto ir2 = gtirb::IR::load(ctx2, ifs)) {\n\n return ir2.get()->modules().empty() ? 0 : 1;\n };\n return 1;\n}\n" }, { "path": ".ci/test-install.lisp", "content": "(in-package :gtirb)\n\n(uiop/stream:with-temporary-file (:pathname path :keep nil)\n (let ((it (make-instance 'gtirb))\n (test-string \"Something.\"))\n (push (cons \"test\" (make-instance 'aux-data)) (aux-data it))\n (setf (aux-data-type (cdar (aux-data it))) :string\n (aux-data-data (cdar (aux-data it))) test-string)\n (write-gtirb it path)\n (assert (string= (aux-data-data (cdar (aux-data (read-gtirb path))))\n test-string)\n (path) \"AuxData in GTIRB at ~s holds ~s.\" path test-string)))\n" }, { "path": ".ci/test-install.py", "content": "import sys\nimport tempfile\n\nimport gtirb\n\nfilename = tempfile.mktemp()\nir = gtirb.IR()\nir.save_protobuf(filename)\nir = gtirb.IR.load_protobuf(filename)\nsys.exit(len(ir.modules))\n" }, { "path": ".ci/test-interop.sh", "content": "#!/bin/bash\nset -e\ncd build\n\nfailures=0\n\ncheck() {\n local creator=$1\n local auxdata=$2\n local consumer=$3\n shift 3\n\n if \"$@\" ; then\n echo $creator $auxdata AuxData work in $consumer\n else\n failures=$(( failures + 1))\n fi\n}\n\n### floating-point compatiblity test\n\nbin/test_floats -w floats_cpp.gtirb\npython3 src/test/testInterop/test_floats.py -w floats_py.gtirb\n\ncheck python float c++ \\\n bin/test_floats -r floats_py.gtirb\ncheck c++ float python \\\n python3 src/test/testInterop/test_floats.py -r floats_cpp.gtirb\n\nrm floats_{cpp,py}.gtirb\n\n### variant compatibility test\n\nbin/test_variants -w variants_cpp.gtirb\npython3 src/test/testInterop/test_variants.py -w variants_py.gtirb\n\ncheck c++ variant python \\\n python3 src/test/testInterop/test_variants.py -r variants_cpp.gtirb\ncheck python variant c++ \\\n bin/test_variants -r variants_py.gtirb\n\nrm variants_{cpp,py}.gtirb\n\ntest $failures = 0\n" }, { "path": ".clang-format", "content": "---\nLanguage: Cpp\n# BasedOnStyle: LLVM\nAccessModifierOffset: -2\nAlignAfterOpenBracket: Align\nAlignConsecutiveAssignments: false\nAlignConsecutiveDeclarations: false\nAlignEscapedNewlinesLeft: false\nAlignOperands: true\nAlignTrailingComments: true\nAllowAllParametersOfDeclarationOnNextLine: true\nAllowShortBlocksOnASingleLine: false\nAllowShortCaseLabelsOnASingleLine: false\nAllowShortFunctionsOnASingleLine: All\nAllowShortIfStatementsOnASingleLine: false\nAllowShortLoopsOnASingleLine: false\nAlwaysBreakAfterDefinitionReturnType: None\nAlwaysBreakAfterReturnType: None\nAlwaysBreakBeforeMultilineStrings: false\nAlwaysBreakTemplateDeclarations: false\nBinPackArguments: true\nBinPackParameters: true\nBraceWrapping:\n AfterClass: false\n AfterControlStatement: false\n AfterEnum: false\n AfterFunction: false\n AfterNamespace: false\n AfterObjCDeclaration: false\n AfterStruct: false\n AfterUnion: false\n BeforeCatch: false\n BeforeElse: false\n IndentBraces: false\nBreakBeforeBinaryOperators: None\nBreakBeforeBraces: Attach\nBreakBeforeTernaryOperators: true\nBreakConstructorInitializersBeforeComma: false\nBreakAfterJavaFieldAnnotations: false\nBreakStringLiterals: true\nColumnLimit: 80\nCommentPragmas: '^ IWYU pragma:'\nConstructorInitializerAllOnOneLineOrOnePerLine: false\nConstructorInitializerIndentWidth: 4\nContinuationIndentWidth: 4\nCpp11BracedListStyle: true\nDerivePointerAlignment: false\nDisableFormat: false\nExperimentalAutoDetectBinPacking: false\nForEachMacros: [ foreach, Q_FOREACH, BOOST_FOREACH ]\n# IncludeBlocks: Regroup\nIncludeCategories:\n - Regex: '^\".*\"'\n Priority: 1\n - Regex: '^.container\" field, despite\n # what the Context Availability documentation says. See:\n # https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability\n - id: vars\n run: |\n export IMAGE_TAG=$([ \"${{ github.ref_name }}\" == \"master\" ] && echo latest || echo ${{ github.ref_name }} | sed -e \"s/\\//-/g\")\n echo \"image_tag=$IMAGE_TAG\" >> $GITHUB_ENV\n echo \"image_tag=$IMAGE_TAG\" >> $GITHUB_OUTPUT\n export IMAGE_PATH=$(echo ghcr.io/${{ github.repository }}/ | awk '{print tolower($0)}')\n echo \"image_path=$IMAGE_PATH\" >> $GITHUB_ENV\n echo \"image_path=$IMAGE_PATH\" >> $GITHUB_OUTPUT\n - uses: actions/checkout@master\n - name: Build image\n env:\n image_reference: ${{ env.image_path }}${{ matrix.os }}\n run: |\n buildah login -u ${{ github.actor }} -p ${{ secrets.GITHUB_TOKEN }} ghcr.io\n buildah build \\\n -f .ci/Dockerfile.${{ matrix.file_suffix }} \\\n --cache-from ${{ env.image_reference }}-cache \\\n --cache-to ${{ env.image_reference }}-cache \\\n --layers \\\n --tag ${{ env.image_reference }}:${{ env.image_tag }}\n buildah push ${{ env.image_reference }}:${{ env.image_tag }}\n\n docs:\n runs-on: ubuntu-latest\n permissions:\n packages: read\n strategy:\n matrix:\n os: [focal]\n needs: docker\n container: ${{ needs.docker.outputs.image_path }}${{ matrix.os }}:${{ needs.docker.outputs.image_tag }}\n steps:\n - name: Checkout\n uses: actions/checkout@v3\n - name: Generate documentation\n run: |\n cmake -DGTIRB_ENABLE_TESTS=OFF -B build .\n cd build/python\n pip install -e '.[doc]'\n cd ..\n cmake ..\n make doc\n mv doc/html ../public\n - name: Upload GitHub Pages artifact\n uses: actions/upload-pages-artifact@v3\n with:\n path: public\n\n deploy-pages:\n needs: docs\n if: github.ref == 'refs/heads/master'\n permissions:\n pages: write\n id-token: write\n\n environment:\n name: github-pages\n url: ${{ steps.deployment.outputs.page_url }}\n\n runs-on: ubuntu-latest\n steps:\n - name: Deploy to GitHub Pages\n id: deployment\n uses: actions/deploy-pages@v4\n" }, { "path": ".gitignore", "content": "*~\n*.fasl\n*.o\n*.out\n*.pc\nout.gtir\nCMakeCache.txt\nCMakeFiles\nCMakeScripts\nTesting\nMakefile\ncmake_install.cmake\ninstall_manifest.txt\ncompile_commands.json\nCTestTestfile.cmake\nbuild/\nbuild-doc/\nbin/\ndoc/html/\ngoogletest-download/\ngoogletest-src/\ngsl-download/\ngsl-src/\ninclude/gsl/\ninclude/proto/\nwiki/\nscratch.lisp\n/include/gtirb/version.h\n/java/com/grammatech/gtirb/proto/\n.mypy_cache/\n__pycache__/\n.vscode/\n\n.gtirb.pdf\n" }, { "path": ".gtirb.tex", "content": "\\begin{tikzpicture}%% Caption: GrammaTech IR for Binaries is a data structure that implicitly represents binary structures required for modification. Elements postifxed with \"(1)\" are singleton in any IR instance every other structure can appear in multiple. Every elements is assigned a Universal Unique Identifier (UUID) which can be used to reference the element from an AuxData table. AuxData tables hold open-ended analysis results.\n %% #fig:gtirb\n [\n object/.style = {draw},\n owner/.style = {thick},\n owner-many/.style = {-triangle 90 reversed,thick},\n reference/.style = {owner, dashed, ->},\n ]\n \\node[object, ] (ir) {IR (1)};\n \\node[object, below right=1em and 2em of ir, text width=6.25em] (ad0) {AuxData};\n \\node[below=0.25em of ad0.south] (ad1) {ID1 \\& DATA1};\n \\node[below=0em of ad1] (ad2) {ID2 \\& DATA2};\n \\node[below=0em of ad2] (ad3) {ID3 \\& DATA3};\n \\node[below=0em of ad3] (ad4) {\\ldots{}};\n \\node[fit={(ad1) (ad4)}, draw, thick, dotted, inner sep=0.25em] (auxdata) {};\n \\node[right=2em of auxdata] (anything) {{\\em any UUID}};\n \\node[object, above right=4.5em and 2em of ir] (cfg) {CFG (1)};\n \\node[object, right=4em of cfg, text width=5em] (edges) {Edges};\n\n \\node[object, right=4em of ir, text width=6em] (modules) {Modules};\n \\node[object, below right=1em and 4em of modules, text width=6em] (symbols) {Symbols};\n\n \\node[object, right=4em of modules, text width=6em] (sections) {Sections};\n\n \\node[object, right=2em of sections, text width=8em] (byteintervals) {ByteIntervals};\n\n \\node[object, above=2em of byteintervals, text width=8em] (proxies) {Proxy blocks};\n \\node[object, right=2.5em of proxies, text width=7em] (codeblocks) {Code Blocks};\n \\node[object, below=0.5em of codeblocks, text width=7em] (datablocks) {Data Blocks};\n \\node[fit={(proxies) (codeblocks)}, draw, thick, dotted] (edgeblocks) {};\n \\node[] at (edges -| proxies) (eblocks) {Edge Blocks};\n \\node[fit={(codeblocks) (datablocks)}, draw, thick, dotted, inner sep=0.75em] (byteblocks) {};\n \\node[] at (eblocks -| byteblocks) (bblocks) {Byte Blocks};\n\n \\node[object, below right=1em and 2.5em of byteintervals, text width=10.5em] (symexpr) {SymbolicExpressions};\n\n %% References\n \\draw[reference] (edges.east) |- (eblocks);\n \\draw[reference] (edges.east) -| ++(2,1) -| (bblocks.north);\n \\draw[reference] (symbols.east) -| ++(2,-1) -| (symexpr.south);\n \\draw[reference] (auxdata) -- (anything);\n\n %% Ownership\n \\draw[owner-many] (ir) -- (modules);\n \\draw[owner] (ir) -- ++(1.0,0) |- (cfg);\n \\draw[owner-many] (ir) -- ++(1.0,0) |- (ad0);\n \\draw[owner-many] (cfg) -- (edges);\n \\draw[owner-many] (modules) -- ++(1.5,0) |- (symbols);\n \\draw[owner-many] (modules) -- (sections);\n \\draw[owner-many] (modules) -- ++(1.5,0) |- (edgeblocks);\n \\draw[owner-many] (modules.south) -- (ad0.north-|modules.south);\n \\draw[owner-many] (sections) -- (byteintervals);\n \\draw[owner-many] (byteintervals) -- ++(1.75,0) |- (symexpr);\n \\draw[owner-many] (byteintervals) -- ++(1.75,0) |- (bblocks);\n\n %% Local Variables:\n %% mode: latex\n %% end:\n\\end{tikzpicture}\n" }, { "path": ".isort.cfg", "content": "# Settings are chosen to be compatible with black:\n# https://black.readthedocs.io/en/stable/the_black_code_style.html#how-black-wraps-lines\n# For details on each setting:\n# https://github.com/timothycrosley/isort/wiki/isort-Settings\n[settings]\nline_length=79\nmulti_line_output=3\ninclude_trailing_comma=true\nforce_grid_wrap=0\n" }, { "path": ".lisp-format", "content": ";;;; -*- emacs-lisp -*-\n;;;;\n;;;; For information about how to use lisp-format see it's\n;;;; documentation, which is available in a comment at the top of the\n;;;; lisp-format script or, equivalently, in the README available at:\n;;;;\n;;;; https://github.com/eschulte/lisp-format\n;;;;\n(mapc (lambda (dir) (add-to-list 'load-path dir))\n (apply #'append\n (mapcar\n (lambda (pkg-glob)\n (cl-loop for path in\n (directory-files\n ;; Use quicklisp if the user has it setup.\n (if (getenv \"QUICK_LISP\")\n (concat (getenv \"QUICK_LISP\") \"/dists/quicklisp/software/\")\n ;; Search for the site-lisp path in load-path\n (add-to-list 'load-path \"/usr/share/emacs25/site-lisp/elpa/\")\n (add-to-list 'load-path \"/usr/share/emacs/site-lisp/elpa/\")\n (cl-loop for path in load-path\n if (and (string-match-p \"site-lisp\" path)\n (file-expand-wildcards (concat (file-name-as-directory path) \"slime*\")))\n do (cl-return path)))\n t pkg-glob)\n if (file-directory-p path) collect path))\n (list \"slime*\" \"paredit*\"))))\n\n(defun verbose-require (package)\n (unless (ignore-errors (require package))\n (message \"Failed to load the package '%S'.\" package)\n (message \"Ensure %s is installed locally, and then edit your\" package)\n (message \"\\\"~/.lisp-formatrc\\\" file adding %s to your load path.\\n\" package)\n (message \" (add-to-list 'load-path )\\n\" package)\n ;; After printing the messages require again to trigger the error.\n (require package)))\n(verbose-require 'slime)\n(verbose-require 'paredit)\n\n(set-default 'indent-tabs-mode nil)\n(pushnew 'untabify *lisp-format-fixers*)\n\n(defun fix-trailing-parens (start end &optional _arg)\n \"Use `paredit-close-parenthesis' to fix trailing parens.\"\n (interactive (if current-prefix-arg\n (list (point-min) (point-max) current-prefix-arg)\n (list (region-beginning) (region-end) nil)))\n (let ((c (current-column)))\n (save-excursion\n (save-restriction\n (narrow-to-region (point-min) end)\n (goto-char start)\n (while (re-search-forward \"^ *)\" nil t)\n (forward-char -1)\n (paredit-close-parenthesis))))\n (move-to-column c)))\n(pushnew 'fix-trailing-parens *lisp-format-fixers*)\n\n;;; Syntax table extension for curry-compose-reader-macros\n(modify-syntax-entry ?\\[ \"(]\" lisp-mode-syntax-table)\n(modify-syntax-entry ?\\] \")[\" lisp-mode-syntax-table)\n(modify-syntax-entry ?\\{ \"(}\" lisp-mode-syntax-table)\n(modify-syntax-entry ?\\} \"){\" lisp-mode-syntax-table)\n(modify-syntax-entry ?\\« \"(»\" lisp-mode-syntax-table)\n(modify-syntax-entry ?\\» \")«\" lisp-mode-syntax-table)\n\n;;; Specify indentation levels for specific functions.\n(mapc (lambda (pair) (put (first pair) 'lisp-indent-function (second pair)))\n '((make-instance 1)\n (if-let 1)\n (if-let* 1)\n (when-let 1)\n (when-let* 1)\n (defixture 1)\n (lambda-bind 1)\n (signals 1)\n (match 1)\n (start-case 1)\n (define-proto-backed-class 4)\n (register-groups-bind 2)))\n\n(defun define-feature-lisp-indent\n (path state indent-point sexp-column normal-indent)\n \"Indentation function called by `lisp-indent-function' for define-feature.\"\n ;; (message \"CALLED: %S\"\n ;; (list 'define-feature-lisp-indent\n ;; path state indent-point sexp-column normal-indent))\n (cond\n ((equalp path '(2)) 2) ; Doc string for enclosing define-feature.\n ((equalp path '(3)) 2) ; Extractor function definition.\n ((equalp path '(3 2)) 4) ; Doc string for extractor.\n ((equalp path '(4)) 2) ; Merge function definition.\n (t nil))) ; Otherwise do the default.\n(put 'define-feature 'lisp-indent-function 'define-feature-lisp-indent)\n" }, { "path": ".pre-commit-config.yaml", "content": "repos:\n - repo: https://github.com/psf/black\n rev: 22.3.0\n hooks:\n - id: black\n args: [\"--line-length\", \"79\"]\n - id: black\n name: black (.pyi)\n args: [\"--line-length\", \"79\"]\n types: [pyi]\n - repo: local\n hooks:\n - id: clang-format\n name: clang-format\n language: system\n files: \\.(c|h|cpp|hpp|proto|java)$\n entry: clang-format -i\n - repo: https://github.com/eschulte/lisp-format\n rev: master\n hooks:\n - id: lisp-format\n name: lisp-format\n args: [-style=file]\n - repo: https://github.com/pre-commit/pre-commit-hooks\n rev: v2.4.0\n hooks:\n - id: end-of-file-fixer\n - id: trailing-whitespace\n args: [\"--chars\",\" \\t\"]\n - id: check-merge-conflict\n - id: check-yaml\n args: [--allow-multiple-documents]\n - id: debug-statements\n - id: mixed-line-ending\n - repo: https://github.com/iconmaster5326/cmake-format-pre-commit-hook\n rev: v0.6.2\n hooks:\n - id: cmake-format\n exclude: build\n - repo: https://github.com/timothycrosley/isort\n rev: 5.13.2\n hooks:\n - id: isort\n files: \\.py$\n - repo: https://github.com/PyCQA/flake8\n rev: 7.1.0\n hooks:\n - id: flake8\n" }, { "path": "AlignOf.cmake", "content": "macro(ALIGNOF TYPE LANG NAME)\n if(NOT ALIGNOF_${NAME})\n #\n # Try to compile and run a foo grogram. The alignment result will be stored\n # in ALIGNOF_${CHECK_TYPE}\n #\n\n set(INCLUDE_HEADERS\n \"#include \n\t\t\t#include \n\t\t\t#include \"\n )\n\n foreach(File ${CMAKE_REQUIRED_INCLUDES})\n set(INCLUDE_HEADERS \"${INCLUDE_HEADERS}\\n#include <${File}>\\n\")\n endforeach()\n\n set(INCLUDE_HEADERS \"${INCLUDE_HEADERS}\\n#include \\n\")\n\n file(\n WRITE\n \"${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/CMakeTmp/c_get_${NAME}_alignment.${LANG}\"\n \"${INCLUDE_HEADERS}\n\t\t\tint main(){\n\t\t\t\tchar diff;\n\t\t\t\tstruct foo {char a; ${TYPE} b;};\n\t\t\t\tstruct foo *p = (struct foo *) malloc(sizeof(struct foo));\n\t\t\t\tdiff = ((char *)&p->b) - ((char *)&p->a);\n\t\t\t\treturn diff;\n\t\t\t}\"\n )\n\n try_run(\n ALIGNOF_${NAME}\n COMPILE_RESULT\n \"${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/CMakeTmp/\"\n \"${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/CMakeTmp/c_get_${NAME}_alignment.${LANG}\"\n COMPILE_OUTPUT_VARIABLE \"ALIGNOF_${NAME}_COMPILE_VAR\"\n )\n\n if(NOT COMPILE_RESULT)\n message(\n FATAL_ERROR\n \"Check alignment of ${TYPE} in ${LANG}: compilation failed: ${ALIGNOF_${NAME}_COMPILE_VAR}\"\n )\n else()\n message(\n STATUS \"Check alignment of ${TYPE} in ${LANG}: ${ALIGNOF_${NAME}}\"\n )\n endif()\n endif()\nendmacro()\n" }, { "path": "AuxData.md", "content": "Standard AuxData Schemata\n=========================\n\nThe \\ref AUXDATA_GROUP class provides generic storage for\napplication-specific data. This allows data to be attached to either\nthe IR or Module classes in GTIRB.\n\nWe specify a small number of standard gtirb::AuxData schemata to\nsupport interoperability. These are listed below, in two sets:\n\n- [Sanctioned](#sanctioned-auxdata-tables) Recommended for GTIRB\n users. Individual schemata are unlikely to change in future,\n although the set of Sanctioned schemata may grow.\n\n- [Provisional](#provisional-auxdata-tables) Under consideration for\n 'sanctioned' status.\n\nFor example, if you want to store alignment requirements for blocks\nand data objects, you can use an [alignment](#alignment) table.\n\n```c++\n// Leverage definitions for the sanctioned AuxData tables.\n#include \n\n// Define your own custom AuxData tables.\n// By convention, we put these in the namespace gtirb::schema.\n//\n// Note that if the custom type requires custom serialization, a\n// specialization of the auxdata_traits template also has to be\n// provided. We provide default specializations for many standard\n// types.\nnamespace gtirb {\nnamespace schema {\nstruct MyAuxDataFoo {\n static constexpr const char* Name = \"foo\";\n typedef Foo Type;\n};\n}\n}\n\nusing namespace gtirb;\nusing namespace schema;\n\n// Register AuxData types before using GTIRB.\nvoid call_me_from_main()\n{\n AuxDataContainer::registerAuxDataType();\n AuxDataContainer::registerAuxDataType();\n}\n\nvoid do_stuff_with_gtirb()\n{\n Context C;\n IR& ir = *IR::Create(C);\n ir.addModule(Module::Create(C));\n Module& module = *ir.modules_begin();\n\n // Attach an empty alignment table to the internal representation\n module.addAuxData(std::map{});\n\n //...\n\n // Create a new block\n Section* section = module.addSection(C, \".text\");\n ByteInterval* interval = section->addByteInterval(C, Addr(400), 1000);\n CodeBlock* b1 = interval->addBlock(C, 64, 6);\n\n // Record that the block should be aligned to 8-byte boundaries.\n // First fetch the map AuxData.\n auto* align_map = module.getAuxData();\n\n // Check for null if you don't know that the module definitely has\n // an existing Alignment AuxData attached.\n if (align_map)\n (*align_map)[b1->getUUID()] = 8;\n\n // Attach a custom \"Foo\" object.\n // Note that AuxData uses a move reference\n Foo my_foo = BuildAFoo();\n module.addAuxData(std::move(my_foo));\n\n // Subsequently access the Foo table through the AuxData interface.\n module.getAuxData()->some_member_function();\n}\n```\n\n\n## Sanctioned AuxData Tables\n\nThe following are the sanctioned AuxData table schemata.\n\n\n| Label | Type |\n|-------------------------------------------|----------------------------------------------------|\n| [`\"elfDynamicInit\"`](#elfDynamicInit) | ```gtirb::UUID``` |\n| [`\"elfDynamicFini\"`](#elfDynamicFini) | ```gtirb::UUID``` |\n| [`\"elfSoname\"`](#elfSoname) | ```std::string``` |\n| [`\"elfStackExec\"`](#elfStackExec) | ```bool``` |\n| [`\"elfStackSize\"`](#elfStackSize) | ```uint64_t``` |\n| [`\"functionBlocks\"`](#functionblocks) | ```std::map>``` |\n| [`\"functionEntries\"`](#functionentries) | ```std::map>``` |\n| [`\"functionNames\"`](#functionnames) | ```std::map``` |\n| [`\"types\"`](#types) | ```std::map``` |\n| [`\"alignment\"`](#alignment) | ```std::map``` |\n| [`\"comments\"`](#comments) | ```std::map``` |\n| [`\"symbolForwarding\"`](#symbolforwarding) | ```std::map``` |\n| [`\"padding\"`](#padding) | ```std::map``` |\n\n\n### elfDynamicInit\n\n| | |\n|----------|----------------------------------------------------|\n| Label | ```\"elfDynamicInit\"``` |\n| Type | ```gtirb::UUID``` |\n| Value | CodeBlock UUID |\n| AttachedTo | gtirb::Module |\n| Note | The CodeBlock to which a DT_INIT entry in an ELF file's .dynamic section refers. |\n\n### elfDynamicFini\n\n| | |\n|----------|----------------------------------------------------|\n| Label | ```\"elfDynamicFini\"``` |\n| Type | ```gtirb::UUID``` |\n| Value | CodeBlock UUID |\n| AttachedTo | gtirb::Module |\n| Note | The CodeBlock to which a DT_FINI entry in an ELF file's .dynamic section refers. |\n\n### elfSoname\n\n| | |\n|----------|----------------------------------------------------|\n| Label | ```\"elfSoname\"``` |\n| Type | ```std::string``` |\n| Value | The SONAME of a library. |\n| AttachedTo | gtirb::Module |\n| Note | The string value which the DT_SONAME entry in an ELF file's .dynamic section contains. |\n\n### elfStackExec\n\n| | |\n|----------|----------------------------------------------------|\n| Label | ```\"elfStackExec\"``` |\n| Type | ```bool``` |\n| Value | Stack executable flag specified by PT_GNU_STACK segment in ELF files. |\n| AttachedTo | gtirb::Module |\n\n### elfStackSize\n\n| | |\n|----------|----------------------------------------------------|\n| Label | ```\"elfStackSize\"``` |\n| Type | ```uint64_t``` |\n| Value | The size of the PT_GNU_STACK segment in ELF files, which may influence the runtime stack size in certain environments. |\n| AttachedTo | gtirb::Module |\n\n### functionBlocks\n\n| | |\n|----------|----------------------------------------------------|\n| Label | ```\"functionBlocks\"``` |\n| Type | ```std::map>``` |\n| Key | Function UUID. |\n| Value | The set of UUIDs of all the blocks (gtirb::CodeBlock) in the function. |\n| AttachedTo | gtirb::Module |\n| Note | This table identifies all of the gtirb::CodeBlocks that belong to each function. These do not necessarily have to be contiguous in the address space. Note that there is no function notion in the core GTIRB IR. A function's UUID is just a unique identifier that is consistently used across all function-related AuxData tables. |\n\n\n### functionEntries\n\n| | |\n|----------|----------------------------------------------------|\n| Label | ```\"functionEntries\"``` |\n| Type | ```std::map>``` |\n| Key | Function UUID. |\n| Value | The set of UUIDs of all the entry blocks (gtirb::CodeBlock) for the function. |\n| AttachedTo | gtirb::Module |\n| Note | This table identifies all gtirb::CodeBlocks that represent entry points to each function. A single function may have more than one entry point. Note that there is no function notion in the core GTIRB IR. A function's UUID is just a unique identifier that is consistently used across all function-related AuxData tables. |\n\n\n### functionNames\n\n| | |\n|----------|---------------------------------------------------------------------|\n| Label | ```\"functionNames\"``` |\n| Type | ```std::map``` |\n| Key | Function UUID. |\n| Value | The UUID of a gtrb::Symbol whose `name` field contains the name of the function. |\n| AttachedTo | gtirb::Module |\n| Note | There may be more than one gtirb::Symbol associated with the address(es) corresponding to the entry point(s) of a function. This table identifies a canonical gtirb::Symbol to be used for each function. Note that there is no function notion in the core GTIRB IR. A function's UUID is just a unique identifier that is consistently used across all function-related AuxData tables. |\n\n\n### types\n\n| | |\n|----------|-----------------------------------------|\n| Label | ```\"types\"``` |\n| Type | ```std::map``` |\n| Key | The gtirb::UUID of a gtirb::DataBlock. |\n| Value | The type of the data, expressed as a std::string containing a C++ type specifier. |\n| AttachedTo | gtirb::Module |\n| Note | An entry in this table indicates that the given gtirb::DataBlock contains content that exhibits the given C++ type. |\n\n\n### alignment\n\n| | |\n|----------|-----------------------------------------------------------|\n| Label | ```\"alignment\"``` |\n| Type | ```std::map``` |\n| Key | The gtirb::UUID of a gtirb::CodeBlock, gtirb::DataBlock, or gtirb::Section. |\n| Value | Alignment requirements for the block/data object/section. |\n| AttachedTo | gtirb::Module |\n| Note | An entry in this table indicates that the given object's address is required to be evenly divisible by the alignment value. Typically the alignment value is a power of 2. |\n\n\n### comments\n\n| | |\n|----------|--------------------------------------------|\n| Label | ```\"comments\"``` |\n| Type | ```std::map``` |\n| Key | The gtirb::Offset of a comment. |\n| Value | A comment string relevant to the specified offset in the specified GTIRB entry. |\n| AttachedTo | gtirb::Module |\n| Note | The gtirb::Offset refers to the UUID of an entity in memory and a byte offset within that entity to indicate the point at which the comment applies. Comments can contain arbitrary content and are likely generated by analysis tools. They often do not (but may) represent comments present in the original source code of the binary. |\n\n\n### symbolForwarding\n\n| | |\n|----------|----------------------------------------------|\n| Label | ```\"symbolForwarding\"``` |\n| Type | ```std::map``` |\n| Key | The gtirb::UUID of the \"from\" gtirb::Symbol. |\n| Value | The gtirb::UUID of the \"to\" gtirb::Symbol. |\n| AttachedTo | gtirb::Module |\n| Note | This table is intended to support cross-module references. A \"from\" symbol in one gtirb::Module may be dynamically bound at runtime to the \"to\" symbol in another gtirb::Module, thereby modeling dynamic library runtime linkage. |\n\n\n### padding\n\n| | |\n|----------|------------------------------------------------|\n| Label | ```\"padding\"``` |\n| Type | ```std::map``` |\n| Key | The gtirb::Offset at which padding is present. |\n| Value | The length of the padding, in bytes. |\n| AttachedTo | gtirb::Module |\n| Note | Padding here may be 0's or it may be valid instructions. An entry in this table indicates that an analysis has determined that at the given gtirb::Offset (UUID of an entity in memory and byte offset into that entity) and length of bytes indicated constitute content that is unused by the program and is only present to ensure alignment of neighboring objects. Note: some disassemblers may still create a gtirb::CodeBlock or gtirb::DataBlock for the same portion of address space that a padding entry covers. |\n\n\n## Provisional AuxData Tables\n\nThe following are the provisional AuxData table schemata.\n\n\n| Label | Type |\n|-------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|\n| [`\"binaryType\"`](#binarytype) | ```std::vector``` |\n| [`\"cfiDirectives\"`](#cfidirectives) | ```std::map, gtirb::UUID>>>``` |\n| [`\"elfSymbolInfo\"`](#elfsymbolinfo) | ```std::map>``` |\n| [`\"elfSymbolVersions\"`](#elfsymbolversions) | ```std::tuple, uint16_t>>, std::map>, std::map>>``` |\n| [`\"encodings\"`](#encodings) | ```std::map``` |\n| [`\"functionNameProbabilities\"`](#functionnameprobabilities) | ```std::map>>>``` |\n| [`\"includedLibraryNames\"`](#includedlibrarynames) | ```std::map``` |\n| [`\"includedLibraryVersions\"`](#includedlibraryversions) | ```std::map``` |\n| [`\"libraries\"`](#libraries) | ```std::vector``` |\n| [`\"libraryPaths\"`](#librarypaths) | ```std::vector``` |\n| [`\"peExportEntries\"`](#peexportentries) | ```std::vector>``` |\n| [`\"peExportedSymbols\"`](#peexportedsymbols) | ```std::vector``` |\n| [`\"peImportEntries\"`](#peimportentries) | ```std::vector>``` |\n| [`\"peImportedSymbols\"`](#peimportedsymbols) | ```std::vector``` |\n| [`\"peResource\"`](#peresource) | ```std::vector, gtirb::Offset, uint64_t>>``` |\n| [`\"profile\"`](#profile) | ```std::map``` |\n| [`\"prototypeTable\"`](#prototypetable) | ```std::map``` |\n| [`\"sccs\"`](#sccs) | ```std::map``` |\n| [`\"sectionProperties\"`](#sectionproperties) | ```std::map>>>``` |\n| [`\"symbolicExpressionSizes\"`](#symbolicexpressionsizes) | ```std::map``` |\n| [`\"typeTable\"`](#typetable) | ```std::map, std::tuple, uint64_t, uint64_t, std::tuple>, gtirb::UUID, std::tuple, tuple>>, std::tuple, gtirb::UUID>>``` |\n\n\n### encodings\n\n| | |\n|----------|------------------------------------------------|\n| Label | ```\"encodings\"``` |\n| Type | ```std::map``` |\n| Key | The gtirb::UUID of a data object. |\n| Value | The encoding of the data object. |\n| AttachedTo | gtirb::Module |\n| Note | Map from (typed) data objects to the encoding of the data, expressed as a std::string containing an assembler encoding specifier: \"string\", \"uleb128\" or \"sleb128\". |\n\n\n### elfSymbolVersions\n\n| | |\n|----------|------------------------------------------------|\n| Label | ```\"elfSymbolVersions\"``` |\n| Type | ```std::tuple, uint16_t>>, std::map>, std::map>>``` |\n| Key | The gtirb::UUID of a section. |\n| Value | The tuple with the ELF section types and flag. |\n| AttachedTo | gtirb::Module |\n| Note | Tuple with symbol version definitions, needed symbol versions, and a mapping of symbol UUIDs to symbol versions. Symbol version definitions are `ElfSymDefs = std::map>, uint16_t>`, a map from symbol version identifiers version definitions. These correspond to `ELFxx_Verdef` entries in the ELF section `.gnu.version_d`. The values in the map are tuples containing the list of versions strings and the verdef flags. The verdef flag may be `VER_FLG_BASE` (0x1), which indicates that the given version definiton is the file itself, and must not be used for matching a symbol. The first element of the list is the version itself, the subsequent elements are predecessor versions. The needed symbol versions are `ElfSymVerNeeded = std::map>`, a map from dynamic library names to the symbol versions that they need. For each library, we have a map from version identifiers to version strings. Finally, symbol UUIDs are mapped to symbol versions as `ElfSymbolVersionsEntries = std::map>`, where the `bool` represents the `HIDDEN` attribute. Symbol version identifiers are `SymbolVersionId = uint16_t` integers. |\n\n\n### cfiDirectives\n\n| | |\n|----------|------------------------------------------------|\n| Label | ```\"cfiDirectives\"``` |\n| Type | ```std::map, gtirb::UUID>>>``` |\n| Key | The gtirb::Offset of a cfi directive. |\n| Value | cfi directive contains: a string describing the directive, a vector of numeric arguments, and an optional symbolic argument (represented with the UUID of the symbol |\n| AttachedTo | gtirb::Module |\n| Note | Map from Offsets to vector of cfi directives. A cfi directive contains: a string describing the directive, a vector of numeric arguments, and an optional symbolic argument (represented with the UUID of the symbol). |\n\n\n### elfSymbolInfo\n\n| | |\n|----------|------------------------------------------------|\n| Label | ```\"elfSymbolInfo\"``` |\n| Type | ```std::map>``` |\n| Key | The gtirb::UUID of a symbol. |\n| Value | The type, binding, and visibility categories of the symbol. |\n| AttachedTo | gtirb::Module |\n| Note | On ELF targets only: Map from symbols to their type, binding, and visibility categories. |\n\n\n### libraries\n\n| | |\n|----------|------------------------------------------------|\n| Label | ```\"libraries\"``` |\n| Type | ```std::vector``` |\n| Value | The name of a library. |\n| AttachedTo | gtirb::Module |\n| Note | Names of the external libraries that are needed dynamically at run time. |\n\n\n### libraryPaths\n\n| | |\n|----------|------------------------------------------------|\n| Label | ```\"libraryPaths\"``` |\n| Type | ```std::vector``` |\n| Value | A path contained in the rpath of the binary. |\n| AttachedTo | gtirb::Module |\n| Note | Paths contained in the rpath of the binary. |\n\n\n### binaryType\n\n| | |\n|----------|------------------------------------------------|\n| Label | ```\"binaryType\"``` |\n| Type | ```std::vector``` |\n| Value | A binary type descriptor. |\n| AttachedTo | gtirb::Module |\n| Note | A set of binary type descriptors e.g. for ELF whether the binary is PIE \"DYN\" or not, \"EXEC\". PE binaries have additional descriptors, \"DLL\" or \"EXE, and subsystem descriptor, e.g. WINDOWS_GUI or WINDOWS_CUI. |\n\n\n### SCCs\n\n| | |\n|----------|------------------------------------------------|\n| Label | ```\"SCCs\"``` |\n| Type | ```std::map``` |\n| Key | The gtirb::UUID of a block |\n| Value | The intra-procedural SCC identifier of the block. |\n| AttachedTo | gtirb::Module |\n| Note | The intra-procedural SCC identifier of each block. |\n\n\n### symbolicExpressionSizes\n\n| | |\n|----------|------------------------------------------------|\n| Label | ```\"symbolicExpressionSizes\"``` |\n| Type | ```std::map``` |\n| Key | The gtirb::Offset of a symbolic expression. |\n| Value | The size of the expression, in bytes. |\n| AttachedTo | gtirb::Module |\n| Note | Map from an Offset of a symbolic expression in a ByteInterval to its extent, a size in bytes. |\n\n\n### peImportEntries\n\n| | |\n|----------|------------------------------------------------|\n| Label | ```\"peImportEntries\"``` |\n| Type | ```std::vector>``` |\n| Value | A tuples containing details of an imported function. |\n| AttachedTo | gtirb::Module |\n| Note | List of tuples detailing an imported function address, ordinal, function name, and library names for PE. |\n\n\n### peExportEntries\n\n| | |\n|----------|------------------------------------------------|\n| Label | ```\"peExportEntries\"``` |\n| Type | ```std::vector>``` |\n| Value | A tuples containing details of an exported function. |\n| AttachedTo | gtirb::Module |\n| Note | List of tuples detailing an exported address, ordinal, and name for PE. |\n\n\n### peImportedSymbols\n\n| | |\n|----------|------------------------------------------------|\n| Label | ```\"peImportedSymbols\"``` |\n| Type | ```std::vector``` |\n| Value | gtirb::UUID of an imported symbol. |\n| AttachedTo | gtirb::Module |\n| Note | UUIDs of the imported symbols for PE. |\n\n\n### peExportedSymbols\n\n| | |\n|----------|------------------------------------------------|\n| Label | ```\"peExportedSymbols\"``` |\n| Type | ```std::vector``` |\n| Value | gtirb::UUID of an exported symbol. |\n| AttachedTo | gtirb::Module |\n| Note | UUIDs of the exported symbols for PE. |\n\n\n### peResource\n\n| | |\n|----------|------------------------------------------------|\n| Label | ```\"peResource\"``` |\n| Type | ```std::vector, gtirb::Offset, uint64_t>>``` |\n| Value | A resource header, data length, and data pointer. |\n| AttachedTo | gtirb::Module |\n| Note | List of PE resources. A resource header, data length, and data pointer. |\n\n### profile\n\n| | |\n|----------|----------------------------------------------------------|\n| Label | ```\"profile\"``` |\n| Type | ```std::map``` |\n| Key | The gtirb::UUID of a gtirb::CodeBlock. |\n| Value | The number of times that block was executed. |\n| AttachedTo | gtirb::Module |\n| Notes | An entry in this table describes how many times a code block was executed. Blocks that are not present in this aux data table should be assumed to have a value of 0, indicating that they were not executed. |\n\n### functionNameProbabilities\n\n| | |\n|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Label | ```\"functionNameProbabilities\"``` |\n| Type | ```std::map>>>``` |\n| Key | Name of the tool that made the predictions. |\n| Value | Map from function UUID to a list of weighted predictions. Each prediction is a tuple of where the score's meaning is tool dependent. Several existing tools use the convention that higher score is a better match and values ranging from 0.0 to 1.0. |\n| AttachedTo | gtirb::Module |\n| Notes | Used to collect results from tools that identify functions and their source libraries. Source library information is tracked in [includedLibraryNames](#includedlibrarynames) and [includedlibraryVersions](#includedlibraryversions). |\n\n\n### includedLibraryNames\n\n| | |\n|------------|------------------------------------------|\n| Label | ```\"includedLibraryNames\"``` |\n| Type | ```std::map``` |\n| Key | Included library UUID. |\n| Value | The name of the library. |\n| AttachedTo | gtirb::Module |\n| Notes | Names of libraries that are included in an executable (i.e., their code is intermingled with the executable code). |\n\n\n### includedlibraryVersions\n\n| | |\n|------------|-----------------------------------------------------------------------------------------------------------------------|\n| Label | ```\"includedLibraryVersions\"``` |\n| Type | ```std::map``` |\n| Key | Included library UUID. |\n| Value | Version string for the included library. |\n| AttachedTo | gtirb::Module |\n| Notes | Versions of libraries that are included in an executable (i.e., their code is intermingled with the executable code). |\n\n\n### sectionProperties\n\n| | |\n|----------|------------------------------------------------|\n| Label | ```\"sectionProperties\"``` |\n| Type | ```std::map>>>``` |\n| Key | The gtirb::UUID of a section. |\n| Value | The tuple with the ELF section types and flag. |\n| AttachedTo | gtirb::Module |\n| Note | Map from section UUIDs to tuples with the ELF section types and flags. |\n\n\n### typeTable\n\n| | |\n|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Label | ```\"typeTable\"``` |\n| Type | ```std::map, std::tuple, uint64_t, uint64_t, std::tuple>, gtirb::UUID, std::tuple, tuple>>, std::tuple, gtirb::UUID>>``` |\n| Key | UUID of the type object |\n| Value | Variant of the object type, where the variants field each represent: Unknown, Bool, Int, Char, Float, Function, Pointer, Array, Struct, Void, Alias, in that order. |\n| AttachedTo | gtirb::Module |\n| Notes | Contains structured type information about objects in the variant. Some empty tuples have been replaced with ```std::tuple``` which is default-initialized to zero since some GTIRB implementations cannot store a 0-length tuple. The corresponding semantics of each type's variant field is the following:
- **Unknown**: ```uint64_t``` - Size of the unknown type
- **Bool**: ```std::tuple``` - default initialized to zero
- **Int**: ```std::tuple``` - A tuple of signedness (1 for signed, 0 for unsigned) and width of int
- **Char**: ```uint64_t``` - Size of the character
- **Float**: ```uint64_t``` - size of the floating point number
- **Function**: ```std::tuple>``` - A tuple of return type UUID, and a list of parameter type UUIDs
- **Pointer**: ```gtirb::UUID``` - UUID of pointed-to type
- **Array**: ```std::tuple``` - A tuple of UUID of the elements of the array, and the number of element sin that array
- **Alias**: ```gtirb::UUID``` - The type being aliased (note this is effectively a `typedef`)
- **Struct**: ```tuple>>``` - A tuple of the size of the structure in total, and a vector of its fields. Each field is represented as a tuple of the offset at which the field is located, and the UUID of the type of that field.
- **Void**: ```std::tuple``` - default initialized to zero |\n\n### prototypeTable\n\n\n| | |\n|------------|--------------------------------------------|\n| Label | ```\"prototypeTable\"``` |\n| Type | ```std::map``` |\n| Key | UUID of the function |\n| Value | UUID of the function type in the typeTable |\n| AttachedTo | gtirb::Module |\n| Notes | Maps functions' UUIDs to their associated typeTable entry for the purpose of giving them prototypes. NOTE: The associated type table entry **must** be a Function type object. |\n" }, { "path": "CHANGELOG.md", "content": "# 2.3.2 (Unreleased)\n\n# 2.3.1\n\n* Fix auxdata table `elfSectionProperties` to `sectionProperties` in the java api\n to match the cpp and python api\n* Switched to use tox for testing the python API.\n\n# 2.3.0\n\n* Fixed a compatibility problem in the Python API that prevented using recent\n releases of protobuf. The Python API on PyPI now requires protobuf 4.21.1 or\n newer.\n* Building the Python API now requires protobuf compiler version 3.19 or later\n for the generated definitions to be compatible with recent protobuf packages.\n The API can still be built with older protobuf compilers, but the result will\n not be compatible with recent protobuf packages.\n* Added support in the C++ API for deserializing set AuxData into unordered_sets.\n* Fixed issue causing compile errors when building with Boost 1.86+.\n* Building the C++ API now requires Boost 1.68 or later.\n* Fixed an obscure build error caused by a missing protobuf compiler. CMake now\n explicitly checks for the protobuf compiler before generating build files.\n\n# 2.2.0\n\n* Move the following utility functions into the `gtirb` namespace:\n `alignAddr`, `alignmentAdjustment`, `BumpPtrAllocator`, `isPowerOf2_64`,\n `SpecificBumpPtrAllocator`, `cast`, `cast_or_null`, `dyn_cast`,\n `dyn_cast_or_null`, `isa`. For backwards compatibility, these functions\n remain available, but deprecated, in the global namespace unless\n `GTIRB_WRAP_UTILS_IN_NAMESPACE` is defined.\n\n# 2.1.0\n\n* Stop generating debian metapackages and packages with the version attached\n to the package name. Updates in the apt-repository now support multiple\n package versions and upgrading `gtirb` with `apt-get upgrade`.\n* Fix performance issue when checking references of ProxyBlocks in Python API.\n* Add elfSoname AuxData definition\n* ByteInterval's blocks' sort order is now thoroughly defined: offset, size,\n kind, decode mode, and UUID. Adjusting these properties during iteration may\n cause blocks to be skipped or visited twice.\n* Added ByteInterval methods to the Python API to look up blocks by offset on.\n\n# 2.0.0\n\n* The Java API has been substantially reworked. Including:\n * Most of the core API classes now have a more polished interface.\n * The API for handling AuxData has been completely redesigned.\n * New testing infrastructure based on JUnit5 has been added.\n * More extensive test cases have been added.\n* Add elfStackExec and elfStackSize AuxData definitions\n* Add `IR.modules_named` helper method to Python API.\n* Add `IR.findModules(String name)` helper method to Java API.\n\n# 1.12.0\n\n* Add elfDynamicInit and elfDynamicFini AuxData definitions\n\n# 1.11.0\n\nNote that this release, due to changes to the protobuf definitions of symbolic\nexpression attributes, is backwards-incompatible with previous GTIRB files.\n\n* Replace symbolic expression attributes with composable labels.\n\n# 1.10.9\n\n* Added support for bool values in AuxData.\n* Added elfSymbolVersions provisional AuxData definition.\n* The GTIRB file format has changed to include a prefix containing a \"magic\"\n identifier and the GTIRB protobuf version number to allow easier id of\n GTIRB files. The change is not backwards compatible. Newer versions of\n GTIRB will not be able to load older GTIRB files.\n* Converted the decode mode from an arbitrary integer into a ProtoBuf enum.\n This obviously breaks compatibility with older GTIRB files.\n\n# 1.10.8\n\n* Ubuntu 18 and gcc7 are no longer supported.\n\n\n# 1.10.7\n\n* Added support for floating-point numbers in AuxData.\n* Disabled testing the Python API using `setup.py test`. The tests can still be\n run using ctest or Python's unittest module.\n* Improved the performance of the Python API's ByteBlock.references property.\n* Fixed a pair of bugs in C++ support for variants in AuxData\n\n# 1.10.6\n\n* Added type annotations to python API and made them available in package.\n* Removed install-python target.\n\n# 1.10.5\n\n* Added various symbolic expression attributes.\n* Updated Java API\n\n# 1.10.4\n\n* Removed SymStackConst support\n* Added variant (union) support for AuxData\n* Removed address and size from modules\n* Modified Module::findSections(string) to return a range instead of iterator\n* Added IR::findSection(string) to C++ API\n\n# 1.10.3\n\n* Added offset helpers to Python API\n* Better support for `std::byte` when working with `ByteInterval`\n* Fixed a bug which manifested when serializing a big-endian IR\n\n# 1.10.2\n\n* Updated \"address\" iteration order to compare size if addresses are the same\n and UUIDs if addresses and sizes are the same so that it can be used to\n store objects in ordered containers.\n* Fixed some bugs where modifying an object's address or size would cause\n findNodeOn to return incorrect results.\n* Improved performance of findNodeOn and findNodeAt queries.\n\n# 1.10.1\n\n* Added module-level endianess flag, for use in archtectures with multiple\n possible endians for its code blocks.\n* Introduce iteration helpers cfgPredecessors and cfgSuccessors.\n\n# 1.9.0\n\n* Introduce attributes for symbolic expressions to the core IR.\n* Reduce asymptotic complexity of iterating over blocks in a large number of\n byte intervals.\n* Fixed bug where searching for blocks by address could return incorrect matches.\n* Fixed bug where `ByteInterval::addBlock` would refuse to move an existing\n block to a new offset if it was already present.\n\n# 1.8.5\n\n* Make Python Offset objects immutable and make Offsets equivalent when they\n refer to the same displacement from the same element.\n\n# 1.8.4\n\n* Fix bug where Symbol iteration could get out of order when symbols refer to\n blocks in byte intervals that are relocated.\n\n# 1.8.3\n\n* Fix bug that didn't add CodeBlocks to the CFG if the CodeBlocks were added to\n a ByteInterval before it was added to the IR.\n\n# 1.8.2\n\n* The C++ API build no longer generates a `libgtirb.so.1` symlink. This has the\n effect of requiring clients to link against the full version number (e.g.,\n `libgtirb.so.1.8.2`) to ensure ABI compatibility while we continue to make\n rapid improvements to the library.\n\n# 1.5.0\n\n* In the Python API:\n * Removed `Node.from_uuid` and added `get_by_uuid` to `IR`s.\n This changes UUID lookup from a global cache to a per-IR cache;\n this means you can now have two IRs exist that share UUIDs but have\n different contents, for example.\n * Added convienience properties to all node types to find the parent nodes\n they belong to.\n\n# 1.4.6\n\n* Implement std::hash for Addr objects.\n\n# 1.4.5\n\n* Explicitly disable copy and move constructors for the Node class hierarchy in\n C++. This avoids a class of errors where nodes cannot be found by\n Node::getByUUID.\n\n# 1.4.4\n\n* Build/install libgtirb.so.1 symlink on linux.\n\n# 1.4.3\n* Remove the python-egg cmake target, add the python-wheel cmake target\n\n# 1.4.2\n\n* Don't use __declspec(dllimport) on Windows.\n\n# 1.4.1\n\n* Add ISA enums for PPC64, ARM64, MIPS32, and MIPS64.\n\n# 1.3.2\n\n* Access functions for converting to/from protobuf are no longer public in the C++ API.\n* The proto library is no longer dllexported.\n* GTIRB_EXPORT_API no longer uses dllimport on the client side.\n\n# 1.3.1\n\n* No longer installs Python files by default. Added a new 'install-python'\n target to install Python files.\n\n# 1.3.0\n\n* Added a new field to symbols, `at_end`, which allows symbols to point to the end\n of their referents as well as the beginning.\n\n# 1.2.1\n\n* Moved protobuf definitions into gtirb.proto package (gtirb::proto namespace\n in C++).\n* Installing the Python API now respects CMAKE_INSTALL_PREFIX and DESTDIR with\n their usual semantics.\n\n# 1.2.0\n\n* AuxData and AuxDataContainer in the C++ API have been reworked to provide cleaner type safety.\n * AuxData is now retrieved directly from an AuxDataContainer using\n\ta schema class that specifies both the name of the AuxData object\n\tas well as its type.\n * Schemata for AuxData types must be registered at process startup\n before GTIRB objects are constructed or unserialized.\n\n# 1.1.1\n\n* Fixed a bug where changing the address of a block caused lookups of symbol\n by address to fail in some cases.\n\n# 1.1.0\n\n* Added a new API for accessing GTIRB, written in Java. This API is not yet\n released, and as such, has missing features, is not yet documented, and may\n change at any time. For more information, look at the contents of the `java`\n directory.\n\n# 1.0.0\n\nThis is a major backwards-incompatible release. The protobuf\nspecification has changed significantly resulting in protobuf version\n1 which is now tracked in `version.txt` in the base of this\nrepository. (The original protobuf version was version 0.) The\nchanges in this release are primarily intended to enable *binary\nrewriting* use cases on GTIRB. Other changes to the protobuf\nspecification are for more general cleanup, simplification, and\nclarification. In addition, a new Common Lisp GTIRB API is now\nincluded along with the C++ and Python APIs. A list of specific\nchanges follows. Complete documentation of all new objects and\nstructures is provided in the GTIRB manual.\n\n* A `version` field is now present on GTIRB IR instances. The value\n of this field is now `1`. The old value of `0` is the protobuf\n default for a missing field.\n* The control flow graph (CFG) is now a child of the IR instead of\n living under a specific module. This means that a multi-module IR\n now has a single pan-module CFG.\n* The `Block` object has been renamed to `CodeBlock` and the\n `DataObject` to `DataBlock`.\n* A new object has been added to the GTIRB `Section`s named\n `ByteInterval`s. This replaces the `ByteMap` in the previous GTIRB\n version. A `ByteInterval` has:\n * An *optional* fixed address indicating its location in memory.\n Without an address the location of the `ByteInterval` is not\n specified allowing it to float to enable easier binary rewriting.\n * A `size` specifying the extend of the `ByteInterval` in memory.\n If this size is larger than the contents of the `ByteInterval`\n then the extension of the `ByteInterval` in memory beyond the end\n of the contents is un-allocated.\n * A byte vector named `contents` holding the contents of the `ByteInterval`.\n * A map from offsets to symbolic expressions.\n * A list of blocks holding `CodeBlock`s and `DataBlock`s.\n* The `address` field has been removed from `Block`s.\n* The `address` and `size` fields have been removed from `Section`s.\n* An offset from the start of their `ByteInterval` have been added to blocks.\n* The following fields have been removed from `Module`s:\n * `image_byte_map`\n * `symbolic_operands`\n * `blocks` and\n * `data`.\n* An entry point stored as a `CodeBlock` has been added to `Module`s.\n* A list of `ByteIntervals` has been added to `Section`s.\n* The `ISAID` enumeration on module is renamed to `ISA`.\n* Instead of an `AuxDataContainer` object we now hold a\n `map` on modules and IRs.\n* The following GTIRB enumerations are modified: `ISA`, `FileFormat`,\n `SymbolKind`, and `SectionFlag`. The goals of these modifications\n is to simplify the enumerations and ensure that all included options\n are both necessary and orthogonal.\n* Sections now include have `SectionFlag`s to store common properties\n such as `readable`, `writeable`, or `executable`.\n\n# 0.3.0\n\n* You can now enable and disable the building of certain APIs when calling CMake,\n via the following flags:\n * `GTIRB_CXX_API` to control the building of the C++ API, on by default\n * `GTIRB_PY_API` to control the building of the Python API, on by default if `python3` is installed on your system\n* The following changes have been made to the Python API:\n * `Serialization.decode` can now take a `bytes` object\n in addition to a `BytesIO` object.\n * If an unknwon type is encountered while decoding `AuxData`,\n it will be placed in `data` as a `bytes`-like object\n instead of throwing a `DecodeError`.\n Unknown data decoded this way can be then encoded again.\n It is still an error to encode unknown types of auxdata\n not in the manner described above.\n* ImageByteMap::setData() has been extended to support arbitrary iterator types.\n* We now build documentation for the Python API using\n [Sphinx](https://www.sphinx-doc.org/en/master/). To generate all\n documentation locally, call `make doc` after calling `cmake`; this will\n generate both C++ and Python API documentation. To only make one or the\n other, call `make doxy` or `make sphinx`, respectively.\n * Making the Sphinx documentation will require the following Python packages:\n ```bash\n pip3 install sphinx sphinx-autodoc-typehints\n ```\n\n# 0.2.0\n\n* Added a new Python API, meant to be a high-level wrapper over the\n Protobuf-generated one. To make use of it, add the `python` folder\n from your build directory to your `PYTHONPATH`. The package is named `gtirb`.\n* CMake now won't automatically download and install its dependencies,\n so that the user has control over which versions are in use.\n The version requirements for Boost and Protobuf are listed in `README.md`.\n* Updated the sanctioned AuxData definitions.\n* Fix for build issue when using Boost 1.71.0.\n\n# 0.1.1\n\n* Initial public release.\n" }, { "path": "CMakeLists.googletest", "content": "cmake_minimum_required(VERSION 2.8.2)\n\nproject(googletest-download NONE)\n\ninclude(ExternalProject)\nexternalproject_add(\n googletest\n GIT_REPOSITORY https://github.com/google/googletest.git\n GIT_TAG v1.15.2\n SOURCE_DIR \"${CMAKE_BINARY_DIR}/googletest-src\"\n BINARY_DIR \"${CMAKE_BINARY_DIR}/googletest-build\"\n CONFIGURE_COMMAND \"\"\n BUILD_COMMAND \"\"\n INSTALL_COMMAND \"\"\n TEST_COMMAND \"\"\n)\n" }, { "path": "CMakeLists.txt", "content": "#\n# Cmake Configuration\n#\n\n# Need 3.10 to support CXX_STANDARD=17 and protobuf::protoc\ncmake_minimum_required(VERSION 3.10.0)\n\n# The version.txt file is the official record of the version number. We use the\n# contents of that file to set the project version for use in other CMake files.\nfile(READ \"${CMAKE_CURRENT_SOURCE_DIR}/version.txt\" ver)\n\nstring(REGEX MATCH \"VERSION_MAJOR ([0-9]*)\" _ ${ver})\nset(GTIRB_MAJOR_VERSION ${CMAKE_MATCH_1})\n\nstring(REGEX MATCH \"VERSION_MINOR ([0-9]*)\" _ ${ver})\nset(GTIRB_MINOR_VERSION ${CMAKE_MATCH_1})\n\nstring(REGEX MATCH \"VERSION_PATCH ([0-9]*)\" _ ${ver})\nset(GTIRB_PATCH_VERSION ${CMAKE_MATCH_1})\n\nstring(REGEX MATCH \"VERSION_PROTOBUF ([0-9]*)\" _ ${ver})\nset(GTIRB_PROTOBUF_VERSION ${CMAKE_MATCH_1})\n\ncmake_policy(SET CMP0048 NEW)\nproject(\n GTIRB\n VERSION \"${GTIRB_MAJOR_VERSION}.${GTIRB_MINOR_VERSION}.${GTIRB_PATCH_VERSION}\"\n)\nset(PACKAGE_BRANCH master)\n\ninclude(CheckFunctionExists)\ninclude(CheckCXXSourceCompiles)\ninclude(CheckIncludeFile)\ninclude(Macros.cmake)\ninclude(AlignOf.cmake)\ninclude(CMakePackageConfigHelpers)\n\noption(ENABLE_CONAN \"Use Conan to inject dependencies\" OFF)\n\nif(ENABLE_CONAN)\n set(CONAN_SYSTEM_INCLUDES ON)\n include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake)\n conan_basic_setup()\nendif()\n\n# ---------------------------------------------------------------------------\n# Build options\n# ---------------------------------------------------------------------------\n\nset(GTIRB_MSVC_PARALLEL_COMPILE_JOBS\n \"0\"\n CACHE\n STRING\n \"Number of parallel compiler jobs used for Visual Studio compiles. 0 means use all processors. Default is 0.\"\n)\n\noption(GTIRB_ENABLE_TESTS \"Enable building and running unit tests.\" ON)\noption(GTIRB_ENABLE_MYPY \"Enable checking python types with mypy.\" ON)\n\n# This just sets the builtin BUILD_SHARED_LIBS, but if defaults to ON instead of\n# OFF.\noption(GTIRB_BUILD_SHARED_LIBS \"Build shared libraries.\" ON)\nif(GTIRB_BUILD_SHARED_LIBS)\n set(BUILD_SHARED_LIBS ON)\nelse()\n set(BUILD_SHARED_LIBS OFF)\nendif()\nif(UNIX AND NOT BUILD_SHARED_LIBS)\n # Find only static libraries\n set(CMAKE_FIND_LIBRARY_SUFFIXES \".a\")\n add_compile_options(-static)\nendif()\n\nenable_testing()\n\n# Set ENABEL_CODE_COVERAGE to default off, unless you want to test c++ coverage\noption(ENABLE_CODE_COVERAGE\n \"Build with instrumentation for collecting code coverage\" OFF\n)\n\nif(ENABLE_CODE_COVERAGE)\n if(${CMAKE_CXX_COMPILER_ID} STREQUAL GNU OR ${CMAKE_CXX_COMPILER_ID} STREQUAL\n Clang\n )\n add_compile_options(--coverage)\n link_libraries(--coverage)\n else()\n message(FATAL_ERROR \"no support for code coverage on this target\")\n endif()\nendif()\n\n# Whether or not to run clang-tidy (if present)\noption(GTIRB_RUN_CLANG_TIDY \"Enable running of clang-tidy.\" ON)\n\n# Define the cache variables for the API options.\noption(GTIRB_CXX_API \"Whether or not the C++ API is built.\" ON)\noption(GTIRB_PY_API \"Whether or not the Python API is built.\" ON)\noption(GTIRB_CL_API \"Whether or not the Common Lisp API is built.\" ON)\noption(GTIRB_JAVA_API \"Whether or not the Java API is built.\" ON)\n\n# Determine whether or not to strip debug symbols and set the build-id. This is\n# only really needed when we are building ubuntu *-dbg packages\noption(GTIRB_STRIP_DEBUG_SYMBOLS\n \"Whether or not to strip debug symbols and set the build-id.\" OFF\n)\n\noption(\n GTIRB_RELEASE_VERSION\n \"Whether or not to build package versions without dev/SNAPSHOT suffixes. Applies to the python and java APIs.\"\n OFF\n)\n\n# Determine whether or not the APIs are REALLY built or not.\n# === C++ ===\nset(CXX_API ${GTIRB_CXX_API})\n\n# === Python ===\nset(PY_API ${GTIRB_PY_API})\nif(GTIRB_PY_API)\n gtirb_find_python()\n\n if(PYTHON)\n set(PYTHON_MINIMUM_VERSION \"3.6\")\n if(\"${Python3_VERSION}\" VERSION_LESS \"${PYTHON_MINIMUM_VERSION}\")\n message(\n WARNING\n \"${PYTHON} --version is ${Python3_VERSION}, which is less than the minimum required, ${PYTHON_MINIMUM_VERSION}; disabling building of API.\"\n )\n set(PY_API OFF)\n endif()\n else()\n message(\n WARNING\n \"Python interpreter not found; disabling building of Python API.\nIf this is in error, try giving -DPYTHON=... to CMake to specify what program to use.\"\n )\n set(PY_API OFF)\n endif()\nendif()\n\n# === Common Lisp ===\n# TODO: test the CL API on other CL interpreters and search for those in\n# addition to SBCL when looking for a default CL interpeter\nset(CL_API ${GTIRB_CL_API})\nif(GTIRB_CL_API)\n find_program(LISP \"sbcl\")\n set(QUICKLISP\n \"$ENV{HOME}/quicklisp\"\n CACHE STRING \"The Quicklisp installation to use.\"\n )\n set(LISP_MINIMUM_VERSION \"1.4.5\")\n\n if(NOT LISP)\n message(\n WARNING\n \"Lisp interpreter not found; disabling building of Lisp API.\nIf this is in error, try giving -DLISP=... to CMake to specify what program to use.\"\n )\n set(CL_API OFF)\n elseif(NOT EXISTS \"${QUICKLISP}\")\n message(\n WARNING\n \"Quicklisp installation not found; disabling building of Lisp API.\nIf this is in error, try giving -DQUICKLISP=... to CMake to specify what directory to use.\"\n )\n set(CL_API OFF)\n else()\n execute_process(COMMAND \"${LISP}\" \"--version\" OUTPUT_VARIABLE LISP_VERSION)\n string(REPLACE \"SBCL\" \"\" LISP_VERSION \"${LISP_VERSION}\")\n string(REPLACE \".debian\" \"\" LISP_VERSION \"${LISP_VERSION}\")\n\n if(\"${LISP_VERSION}\" VERSION_LESS \"${LISP_VERSION}\")\n message(\n WARNING\n \"${LISP} --version is ${LISP_VERSION}, which is less then the minimum required, ${LISP_MINIMUM_VERSION}; disabling building of API.\"\n )\n set(CL_API OFF)\n endif()\n endif()\nendif()\n\n# === Java ===\nset(JAVA_API ${GTIRB_JAVA_API})\nif(GTIRB_JAVA_API)\n find_package(Java 1.8.0 COMPONENTS Development)\n if(NOT JAVA_FOUND)\n message(WARNING \"Java 8 compiler not found; disabling building of Java API.\nIf this is in error, try setting the environment variable $JAVA_HOME.\"\n )\n set(JAVA_API OFF)\n else()\n find_program(MVN mvn)\n if(NOT MVN)\n message(\n WARNING\n \"Maven not found; disabling building of Java API. If this is in \"\n \"error, try setting -DMVN= on the CMake command-line\"\n )\n set(JAVA_API OFF)\n endif()\n endif()\nendif()\n\n# Documentation options.\noption(GTIRB_DOCUMENTATION \"Whether or not documentation is built.\" ON)\n\n# ---------------------------------------------------------------------------\n# Global settings\n# ---------------------------------------------------------------------------\n\nset_property(GLOBAL PROPERTY USE_FOLDERS ON)\nset(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/src)\nif(WIN32)\n set(CMAKE_DEBUG_POSTFIX\n \"d\"\n CACHE STRING \"add a postfix, usually d on windows\"\n )\nendif()\nset(CMAKE_RELEASE_POSTFIX\n \"\"\n CACHE STRING \"add a postfix, usually empty on windows\"\n)\nset(CMAKE_RELWITHDEBINFO_POSTFIX\n \"\"\n CACHE STRING \"add a postfix, usually empty on windows\"\n)\nset(CMAKE_MINSIZEREL_POSTFIX\n \"\"\n CACHE STRING \"add a postfix, usually empty on windows\"\n)\nset(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)\nset(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)\nset(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)\n\nif(CXX_API)\n # Use C++17\n set(CMAKE_CXX_STANDARD 17)\n # Error if it's not available\n set(CMAKE_CXX_STANDARD_REQUIRED ON)\n\n # Specifically check for gcc-7 or later. gcc-5 is installed on many systems\n # and will accept -std=c++17, but does not fully support the standard.\n if(CMAKE_CXX_COMPILER_ID STREQUAL \"GNU\")\n if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS \"7.0.0\")\n message(FATAL_ERROR \"gcc 7 or later is required to build gtirb\")\n endif()\n endif()\n\n set(CMAKE_CXX_VISIBILITY_PRESET hidden)\n\n #\n # Global Options (Compile / Link)\n #\n add_compile_options(-DBOOST_MULTI_INDEX_DISABLE_SERIALIZATION)\n\n # MSVC-specific Options\n if(${CMAKE_CXX_COMPILER_ID} STREQUAL MSVC)\n if(NOT GTIRB_MSVC_PARALLEL_COMPILE_JOBS STREQUAL \"1\")\n if(GTIRB_MSVC_PARALLEL_COMPILE_JOBS STREQUAL \"0\")\n add_compile_options(-MP)\n message(STATUS \"Parallel compilation enabled\")\n else()\n add_compile_options(-MP${GTIRB_MSVC_PARALLEL_COMPILE_JOBS})\n message(\n STATUS\n \"Parallel compilation with ${GTIRB_MSVC_PARALLEL_COMPILE_JOBS} jobs\"\n )\n endif()\n else()\n message(STATUS \"Parallel compilation disabled\")\n endif()\n\n add_compile_options(-D_CRT_SECURE_NO_WARNINGS)\n add_compile_options(-D_MBCS)\n add_compile_options(-D_SCL_SECURE_NO_WARNINGS)\n # We need to add both so that there is not a mismatch between Win32 SDK\n # headers (which use UNICODE) and C Standard Library headers (which use\n # _UNICODE).\n add_compile_options(-D_UNICODE)\n add_compile_options(-DUNICODE)\n add_compile_options(-D_WIN32)\n # Disable macro definitions for min and max that conflict with the STL.\n add_compile_options(-DNOMINMAX)\n # Enable RTTI. FIXME: stop using typeid so we can disable this and add -fno-\n # rtti to the Clang/GCC compiler options.\n add_compile_options(-GR)\n # Enable exceptions, which are basically required because of our reliance on\n # boost.\n add_compile_options(-EHsc)\n # Enabled a sensible warning level and treat all warnings as errors.\n add_compile_options(-W4)\n add_compile_options(-WX)\n\n # Enable bigobj support, otherwise IR.cpp and Module.cpp will refuse to\n # compile due to execeeding the number of sections allowed in an object\n # file. FIXME: we should not have that many template instantiations.\n add_compile_options(-bigobj)\n\n add_compile_options(-sdl) # Enable extra security checks\n add_compile_options(-permissive-) # Disable permissive mode\n\n add_compile_options(-wd4996) # VC8: Deprecated libc functions.\n # This is a warning about a change in behavior from old versions of visual\n # c++. We want the new (standard-compliant) behavior, so we don't want the\n # warning. The warning is that using an array in a class initializer list\n # will cause its elements to be default initialized.\n add_compile_options(-wd4351)\n add_compile_options(-wd4146) # unary minus operator applied to unsigned\n # type, result still unsigned\n\n # C4505: 'google::protobuf::internal::MapField<...>::ContainsMapKey':\n # unreferenced local function has been removed\n add_compile_options(-wd4505)\n\n # C4267: protobuf-generated headers, at least w/ protobuf 3.9.1, trigger\n # MSVC's \"conversion from 'size_t' to 'int', possible loss of data\" warning.\n add_compile_options(-wd4267)\n\n # Release target options\n add_compile_options($<$:-GL>) # Enable whole program\n # optimization\n add_link_options($<$:-ltcg>) # Enable link-time code\n # generation\n elseif((${CMAKE_CXX_COMPILER_ID} STREQUAL GNU) OR (${CMAKE_CXX_COMPILER_ID}\n STREQUAL Clang)\n )\n add_compile_options(-Wall -Wextra -Wpointer-arith -Wshadow -Werror)\n add_compile_options(-fPIC)\n endif()\nendif()\n\n# ---------------------------------------------------------------------------\n# Boost\n# ---------------------------------------------------------------------------\nif(CXX_API)\n find_package(Boost 1.68 REQUIRED)\n\n add_compile_options(-DBOOST_CONFIG_SUPPRESS_OUTDATED_MESSAGE)\n add_compile_options(-DBOOST_SYSTEM_NO_DEPRECATED)\n\n # Boost versions 1.70.0+ may use Boost's provided CMake support rather than\n # CMake's internal Boost support. The former uses \"Boost::boost\" and so on,\n # while the latter uses \"Boost_BOOST\" and so on. This normalizes the two cases\n # to use Boost_INCLUDE_DIRS and Boost_LIBRARIES.\n if(TARGET Boost::headers)\n get_target_property(\n Boost_INCLUDE_DIRS Boost::headers INTERFACE_INCLUDE_DIRECTORIES\n )\n endif()\n\n include_directories(SYSTEM ${Boost_INCLUDE_DIRS})\nendif()\n\n# ---------------------------------------------------------------------------\n# Google Test Application\n# ---------------------------------------------------------------------------\nif(GTIRB_ENABLE_TESTS AND CXX_API)\n # Pull in Google Test\n # https://github.com/google/googletest/tree/master/googletest#incorporating-\n # into-an-existing-cmake-project\n\n # Download and unpack googletest at configure time\n configure_file(CMakeLists.googletest googletest-download/CMakeLists.txt)\n\n execute_process(\n COMMAND \"${CMAKE_COMMAND}\" -G \"${CMAKE_GENERATOR}\" .\n RESULT_VARIABLE result\n WORKING_DIRECTORY \"${CMAKE_BINARY_DIR}/googletest-download\"\n )\n\n if(result)\n message(WARNING \"CMake step for googletest failed: ${result}\")\n endif()\n\n execute_process(\n COMMAND \"${CMAKE_COMMAND}\" --build .\n RESULT_VARIABLE result\n WORKING_DIRECTORY \"${CMAKE_BINARY_DIR}/googletest-download\"\n )\n\n if(result)\n message(WARNING \"Build step for googletest failed: ${result}\")\n endif()\n\n # Prevent overriding the parent project's compiler/linker settings on Windows\n set(gtest_force_shared_crt\n ON\n CACHE BOOL \"\" FORCE\n )\n\n # Add googletest directly to our build. This defines the gtest and gtest_main\n # targets.\n add_subdirectory(\n \"${CMAKE_BINARY_DIR}/googletest-src\" \"${CMAKE_BINARY_DIR}/googletest-build\"\n EXCLUDE_FROM_ALL\n )\n\n include_directories(\"${gtest_SOURCE_DIR}/include\")\nendif()\n\n# ---------------------------------------------------------------------------\n# JUnit Test Application\n# ---------------------------------------------------------------------------\nif(GTIRB_ENABLE_TESTS AND JAVA_API)\n include(ExternalProject)\n externalproject_add(\n junit\n PREFIX ${CMAKE_BINARY_DIR}/junit\n URL \"https://repo1.maven.org/maven2/org/junit/platform/junit-platform-console-standalone/1.10.0/junit-platform-console-standalone-1.10.0.jar\"\n CONFIGURE_COMMAND \"\"\n BUILD_COMMAND \"\"\n INSTALL_COMMAND \"\"\n TEST_COMMAND \"\"\n DOWNLOAD_NO_EXTRACT ON\n )\n\n set(JUNIT_STANDALONE_JAR\n ${CMAKE_BINARY_DIR}/junit/src/junit-platform-console-standalone-1.10.0.jar\n )\nendif()\n\n# ---------------------------------------------------------------------------\n# protobuf\n# ---------------------------------------------------------------------------\nif(CL_API)\n find_package(Protobuf 3.7.0 REQUIRED)\nelse()\n find_package(Protobuf 3.0.0 REQUIRED)\nendif()\nif(NOT Protobuf_PROTOC_EXECUTABLE)\n # find_package only fails if the protobuf libraries or headers cannot be\n # found. It does not treat failing to find the protobuf compiler as an error,\n # so we do that explicitly here.\n message(\n FATAL_ERROR\n \"Could not find Protobuf compiler 'protoc'. Please make sure the \"\n \"Protobuf compiler is installed.\"\n )\nendif()\n\nif(Protobuf_VERSION VERSION_LESS 3.2)\n add_definitions(-DPROTOBUF_SET_BYTES_LIMIT)\nendif()\n\nif(NOT BUILD_SHARED_LIBS)\n set(Protobuf_USE_STATIC_LIBS ON)\nendif()\ninclude_directories(SYSTEM ${PROTOBUF_INCLUDE_DIRS})\n\nadd_subdirectory(proto)\n\n# ---------------------------------------------------------------------------\n# gtirb sources\n# ---------------------------------------------------------------------------\nif(CXX_API)\n add_subdirectory(src)\nendif()\n\nif(PY_API)\n add_subdirectory(python)\nendif()\n\nif(CL_API)\n add_subdirectory(cl)\nendif()\n\nif(JAVA_API)\n add_subdirectory(java)\nendif()\n\nif(GTIRB_DOCUMENTATION)\n add_subdirectory(doc)\nendif()\n\n# ---------------------------------------------------------------------------\n# Export config for use by other CMake projects\n# ---------------------------------------------------------------------------\n\nif(CXX_API)\n # --- For direct use from the build directory/cmake registry ---\n # This exports the targets\n export(TARGETS gtirb gtirb_proto\n FILE \"${CMAKE_CURRENT_BINARY_DIR}/gtirbTargets.cmake\"\n )\n # This is the main config file that find_package will look for.\n configure_file(\n \"${CMAKE_CURRENT_LIST_DIR}/gtirbConfig.cmake.in\"\n \"${CMAKE_CURRENT_BINARY_DIR}/gtirbConfig.cmake\" @ONLY\n )\n # Add the build directory to the user CMake registry, so find_package can\n # locate it automatically.\n export(PACKAGE gtirb)\n\n # --- For the installed copy ---\n # Main config file for find_package, includes the targets file and defines the\n # check_gtirb_branch function.\n if(NOT DEFINED PACKAGE_BRANCH)\n set(PACKAGE_BRANCH \"No package branch specified\")\n endif()\n # FIXME: The installed version of gtirbConfig currently contains the\n # check_gtirb_branch function, which requires users to explicitly call it. We\n # ought to move this functionality to gtirbConfig-version, so that checking\n # the gtirb version also checks the branch, requiring users to opt-out of the\n # branch check, rather than opt-in by calling check_gtirb_branch. See: GitLab\n # issue #93\n configure_file(\n \"${CMAKE_CURRENT_LIST_DIR}/gtirbConfig.cmake.in\"\n \"${CMAKE_CURRENT_BINARY_DIR}/export/gtirbConfig.cmake\" @ONLY\n )\n\n # In this mode, find_package also seems to require a version file\n set(version_file \"${CMAKE_CURRENT_BINARY_DIR}/gtirbConfig-version.cmake\")\n write_basic_package_version_file(\n ${version_file}\n VERSION ${GTIRB_VERSION}\n COMPATIBILITY AnyNewerVersion\n )\n\n # Copy the config files to the install location\n install(\n FILES ${CMAKE_CURRENT_BINARY_DIR}/export/gtirbConfig.cmake ${version_file}\n DESTINATION lib/gtirb\n COMPONENT cmake_config\n )\n # This exports the targets to the install location.\n install(\n EXPORT gtirbTargets\n COMPONENT cmake_target\n DESTINATION lib/gtirb\n )\nendif()\n\n# ---------------------------------------------------------------------------\n# Package policy enforcement\n# ---------------------------------------------------------------------------\n\nif(GTIRB_PACKAGE_POLICY)\n set(PACKAGE_POLICY ${GTIRB_PACKAGE_POLICY})\nelseif(ENABLE_CONAN OR WIN32)\n set(PACKAGE_POLICY conan)\nelse()\n set(PACKAGE_POLICY unix)\nendif()\n\nif(PACKAGE_POLICY STREQUAL \"unix\")\n\n # Provides copyright file for Unix packages.\n install(\n FILES ${CMAKE_SOURCE_DIR}/LICENSE.txt\n COMPONENT license\n DESTINATION share/doc/gtirb\n RENAME copyright\n )\n\nelseif(PACKAGE_POLICY STREQUAL \"conan\")\n\n # Provides LICENSE.txt for Conan packages\n install(\n FILES ${CMAKE_SOURCE_DIR}/LICENSE.txt\n COMPONENT license\n DESTINATION licenses\n )\n\nendif()\n\n# ---------------------------------------------------------------------------\n# Package generation with cpack\n# ---------------------------------------------------------------------------\nset(CPACK_PROJECT_CONFIG_FILE ${CMAKE_CURRENT_SOURCE_DIR}/cpack-config.cmake)\n\nset(CMAKE_PROJECT_HOMEPAGE_URL https://github.com/GrammaTech/gtirb)\nset(CPACK_PACKAGE_VERSION_MAJOR ${GTIRB_MAJOR_VERSION})\nset(CPACK_PACKAGE_VERSION_MINOR ${GTIRB_MINOR_VERSION})\nset(CPACK_PACKAGE_VERSION_PATCH ${GTIRB_PATCH_VERSION})\nset(CPACK_PACKAGE_VENDOR \"GrammaTech Inc.\")\nset(CPACK_PACKAGE_CONTACT gtirb@grammatech.com)\nset(CPACK_PACKAGE_DESCRIPTION_FILE ${CMAKE_CURRENT_SOURCE_DIR}/README.md)\nset(CPACK_PACKAGE_RESOURCE_FILE_LICENSE ${CMAKE_CURRENT_SOURCE_DIR}/LICENSE.md)\nset(CPACK_PACKAGE_DESCRIPTION_SUMMARY\n \"The GrammaTech Intermediate Representation for Binaries (GTIRB) is a machine code analysis and rewriting data structure.\"\n)\nset(CPACK_DEBIAN_PACKAGE_SECTION devel)\n\nstring(REGEX MATCH \"([^\\.]+)\\.([^\\.]+)\\.([^\\.]+)\" PROTOBUF_VERSION_MATCH\n ${Protobuf_VERSION}\n)\nset(PROTOBUF_MAJOR_VERSION ${CMAKE_MATCH_1})\nset(PROTOBUF_MINOR_VERSION ${CMAKE_MATCH_2})\nset(PROTOBUF_PATCH_VERSION ${CMAKE_MATCH_3})\nmath(EXPR NEXT_PROTOBUF_PATCH \"${PROTOBUF_PATCH_VERSION}+1\")\nset(CPACK_PROTOBUF_VERSION_UPPER_BOUND\n \"${PROTOBUF_MAJOR_VERSION}.${PROTOBUF_MINOR_VERSION}.${NEXT_PROTOBUF_PATCH}\"\n)\nset(CPACK_PROTOBUF_VERSION_LOWER_BOUND \"${Protobuf_VERSION}\")\nset(CPACK_GTIRB_VERSION \"${GTIRB_VERSION}\")\nset(CPACK_SOURCE_DIR ${CMAKE_SOURCE_DIR})\n\ninclude(CPack)\n\n# ---------------------------------------------------------------------------\n# Report APIs and features built\n# ---------------------------------------------------------------------------\n\nmessage(\"APIs to be built:\")\nmessage(\" C++ ${CXX_API}\")\nmessage(\" Python ${PY_API}\")\nmessage(\" Lisp ${CL_API}\")\nmessage(\" Java ${JAVA_API}\")\n" }, { "path": "CODE_OF_CONDUCT.md", "content": "# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nIn the interest of fostering an open and welcoming environment, we as\ncontributors and maintainers pledge to making participation in our project and\nour community a harassment-free experience for everyone, regardless of age, body\nsize, disability, ethnicity, sex characteristics, gender identity and expression,\nlevel of experience, education, socio-economic status, nationality, personal\nappearance, race, religion, or sexual identity and orientation.\n\n## Our Standards\n\nExamples of behavior that contributes to creating a positive environment\ninclude:\n\n* Using welcoming and inclusive language\n* Being respectful of differing viewpoints and experiences\n* Gracefully accepting constructive criticism\n* Focusing on what is best for the community\n* Showing empathy towards other community members\n\nExamples of unacceptable behavior by participants include:\n\n* The use of sexualized language or imagery and unwelcome sexual attention or\n advances\n* Trolling, insulting/derogatory comments, and personal or political attacks\n* Public or private harassment\n* Publishing others' private information, such as a physical or electronic\n address, without explicit permission\n* Other conduct which could reasonably be considered inappropriate in a\n professional setting\n\n## Our Responsibilities\n\nProject maintainers are responsible for clarifying the standards of acceptable\nbehavior and are expected to take appropriate and fair corrective action in\nresponse to any instances of unacceptable behavior.\n\nProject maintainers have the right and responsibility to remove, edit, or\nreject comments, commits, code, wiki edits, issues, and other contributions\nthat are not aligned to this Code of Conduct, or to ban temporarily or\npermanently any contributor for other behaviors that they deem inappropriate,\nthreatening, offensive, or harmful.\n\n## Scope\n\nThis Code of Conduct applies within all project spaces, and it also applies when\nan individual is representing the project or its community in public spaces.\nExamples of representing a project or community include using an official\nproject e-mail address, posting via an official social media account, or acting\nas an appointed representative at an online or offline event. Representation of\na project may be further defined and clarified by project maintainers.\n\n## Enforcement\n\nInstances of abusive, harassing, or otherwise unacceptable behavior may be\nreported by contacting the project team at gtirb-conduct@grammatech.com. All\ncomplaints will be reviewed and investigated and will result in a response that\nis deemed necessary and appropriate to the circumstances. The project team is\nobligated to maintain confidentiality with regard to the reporter of an incident.\nFurther details of specific enforcement policies may be posted separately.\n\nProject maintainers who do not follow or enforce the Code of Conduct in good\nfaith may face temporary or permanent repercussions as determined by other\nmembers of the project's leadership.\n\n## Attribution\n\nThis Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,\navailable at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html\n\n[homepage]: https://www.contributor-covenant.org\n\nFor answers to common questions about this code of conduct, see\nhttps://www.contributor-covenant.org/faq\n" }, { "path": "CONTRIBUTING.md", "content": "Contributing\n============\n\n\n## Code of Conduct\n\nPlease read the [GTIRB Code of Conduct](CODE_OF_CONDUCT.md).\n\n## General Guidelines\n\n- Text files may not have trailing whitespace.\n\n- Text files must end with a trailing newline.\n\n- All tests should be able to run and pass.\n This can be checked by running `make check` on your build directory\n after running `cmake`.\n\n- All CMake files shall be formatted with\n [cmake-format](https://pypi.org/project/cmake-format/). A\n `.cmake-format` file is provided in the root directory for the\n project, and a pass through this tool is included as part of our\n `pre-commit` configuration (see below for details).\n\n- The GTIRB version saved in `version.txt` uses\n [semantic versioning](https://semver.org)\n\n- We also track a Protobuf version number in `version.txt` (as\n `VERSION_PROTOBUF`). This number is incremented whenever our\n protobuf files (under `proto/` in the GTIRB repository) are changed\n in any way that affects the serialized protobuf -- even if the\n change could potentially be backwards compatible because of the way\n protobuf gracefully handles unknown new fields.\n\n- We ask that all contributors complete our Contributor License\n Agreement (CLA), which can be found at\n [GrammaTech-CLA-GTIRB.pdf](./GrammaTech-CLA-GTIRB.pdf), and email\n the completed form to `CLA@GrammaTech.com`. Under this agreement\n contributors retain the copyright to their work but grants\n GrammaTech unlimited license to the work.\n\n### pre-commit\n\nIn general, code must follow a unified format. To make compliance with\nthis format easier, we recommend the use of\n[`pre-commit`](https://pre-commit.com/) with the provided\nconfiguration file, `.pre-commit-config.yaml`, to manage formatting.\nTo use `pre-commit`:\n\n1. If `pre-commit` is not already installed on your system, install it\n now with [`pip`](https://pypi.org/project/pip/).\n ```shell\n pip3 install pre-commit\n ```\n2. If [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html)\n is not already installed on your system, install it now.\n3. Install the formatters as a pre-commit hook. In the gtirb root directory:\n ```shell\n pre-commit install\n ```\n If you prefer to run `pre-commit` manually instead, run this before all commits:\n ```shell\n pre-commit run\n ```\n\n## C++ Code Requirements\n\n- All code shall be formatted with [clang-format](https://clang.llvm.org/docs/ClangFormat.html).\n A `.clang-format` is provided in the root directory for the project,\n and a pass through this tool is included as part of our `pre-commit` configuration.\n\n- Code should generally follow the C++ Core Guidelines recommendations.\n\n- Code should generally allow for thread safety.\n\t- No static variables.\n\t- No globals\n\t- Free functions should not maintain state.\n\t- Use caution when using iterators to guard against invalidation.\n\n- Maintain const-correctness.\n\n- Use UpperCamelCase for type names.\n\n- Use UpperCamelCase for enum members.\n\n- Use UpperCamelCase for variable and class members.\n\n- Use lowerCamelCase for function and method names.\n\n- Avoid `using namespace std`\n\n- Use `auto` when the deduced type is explicitly spelled out in the\n initialization or if the deduced type is an abstract type\n alias. Always explicitly specify type qualifiers, pointers, and\n references. E.g.,\n ```cpp\n const auto *Ptr = dynamic_cast(SomePtr);\n auto Val = static_cast(SomeValue);\n for (auto Iter = SomeContainer.begin(), End = SomeContainer.end(); Iter != End; ++Iter) {}\n ```\n\n- Use `auto` to make code more readable, but prefer `auto &` or `auto *`\n to avoid unexpected copies.\n\n- `#include` as little as possible to reduce compile times. Use\n forward declarations of classes when possible to avoid including\n their definitions.\n\n- Do not introduce variables to the code that would require a client\n to dllimport them. Export.hpp does not setup dllimport declarations\n for clients. For example, do not add static function-local variables\n in inline functions in header files.\n\n## Build Performance Tips\n\nSome tips to keep in mind to not needlessly regress build performance when\nworking with GTIRB:\n\n- Do not include a protobuf header from within a .hpp file unless you need the\n enum values from protobuf. A forward declare + include in the .cpp file is\n sufficient and cuts out 100s of transitive headers to parse.\n- CFG.hpp and ByteInterval.hpp are the most expensive headers you can possibly\n include. Avoid including these whenever humanly possible (getting rid of 2\n includes of CFG.hpp cut out ~2500 transitive header includes).\n- Boost headers are extremely heavy to parse, try to push as much of their\n inclusions down into a .cpp file as possible. For instance, including boost's\n endian header requires ~200 transitive headers by itself. Things like the\n boost containers are considerably more expensive. This is what contributes to\n ByteInterval and CFG being so expensive to include. Be wary when adding\n includes to boost headers or adding new boost dependencies.\n- Do not blindly trust the output from tools like include what you use; they\n sometimes do silly things like include a header file when a forward declare is\n sufficient. When adding an include to a .hpp file, try hard to avoid adding\n the include.\n\n### Testing Development\n\n- All code you care about should be tested.\n- Any code you don't care about should be removed.\n- C++ code should be tested on Linux using GCC and Clang, and on Windows using Visual Studio.\n- Code testing is done via Google Test.\n- Test names are prefixed with the type of test they are (`Unit_`, `System_`, `Integration_`).\n- No unit test should take more than 0.5 seconds.\n\n## Building under Windows\n\nMost of the build issues on Windows arise from having to define the location of\nmany dependencies.\n\n### Troubleshooting\n- When using a batch file to call `cmake`, make sure to quote all paths and\n escape all backshlases in paths. i.e. `-DCMAKE_PREFIX_PATH=\"c:\\\\Program\nFiles\\\\capstone\"` and do not leave a trailing backslash on paths.\n- Use `-Dprotobuf_DEBUG=ON` for protobuf related build issues in general.\n- `'../src/gtirb/proto/protobuf::protoc', needed by\n 'src/gtirb/proto/AuxData.pb.h', missing and no known rule to make it`\n - due to missing or unusable protoc protobuf compiler. You may need to define\n `-Dprotobuf_EXECUTABLE=\"\"`, or check that the\nCMAKE_PREFIX_PATH has a path to the protobuf dir (resulting from `ninja install`\nafter building).\n- `CMAKE_PREFIX_PATH` is not additive. If you set it again, it will silently\n overwrite prior settings. Add to the one definition, separtaing with\nsemi-colons.\n\n## Python Code Requirements\n\n- Code must be [PEP8](https://www.python.org/dev/peps/pep-0008/) compliant.\n To check for PEP8 compliance, [flake8](https://pypi.org/project/flake8/) is recommended,\n and included as part of our `pre-commit` configuration.\n\n- All code must be formatted with [Black](https://pypi.org/project/black/)\n (set to line lengths of 79, for PEP8 compliance).\n A pass through this tool is included as part of our `pre-commit` configuration.\n\n- The Python API should be made to run on all versions of Python 3.\n\n- Use `UpperCamelCase` for type names, `UPPER_CASE` for constant names,\n and `snake_case` for other identifier names.\n\n### Testing Development\n\n- All code you care about should be tested.\n- Any code you don't care about should be removed.\n- Code testing is done via the built-in `unittest` framework.\n- Code testing uses [`tox`](https://tox.wiki/en/stable/) and\n [`pytest`](https://docs.pytest.org/en/stable/) to simplify testing supported\n configurations.\n- No unit test should take more than 0.5 seconds.\n\n## Documentation\n\nThe GTIRB documentation consists of complete documentation for all\ncomponents of the GTIRB API, along with examples and other usage\ninformation.\n\n\n### Building Documentation\n\nAt minimum, you will need [CMake](https://cmake.org/) and\n[Doxygen](http://www.doxygen.nl/). To build the documentation:\n\n1. Create and change to a temporary build directory. We will refer to\n this directory as `build`.\n\n ```bash\n > mkdir build\n > cd build\n ```\n\n2. Build the documentation.\n\n ```bash\n build> cmake []\n build> cmake --build . --target doc\n ```\n\n3. Open the documentation home page `build/doc/html/index.html`\n in your browser.\n\n\nThe `` are as follows\n\n- `-DGTIRB_CXX_API=OFF` : do not generate C++ API documentation.\n\n If this option is not specified, `cmake` will attempt to generate\n C++ API documentation, failing (along with the documentation build\n as a whole) if [Doxygen](http://www.doxygen.nl/) is not available.\n\n\n- `-DGTIRB_CL_API=OFF` : do not generate Common Lisp API documentation.\n\n If this option is not specified, `cmake` will attempt to generate\n Common Lisp API documentation if and only if it can locate a\n SBCL/Quicklisp installation, failing if\n [simpler-documentation-template\n (SDT)](https://github.com/eschulte/simpler-documentation-template)\n is not available.\n\n- `-DGTIRB_PY_API=OFF` : do not generate Python API documentation.\n\n If this option is not specified, `cmake` will attempt to generate\n Python API documentation if and only if it can locate a Python\n installation, failing if [Sphinx](https://www.sphinx-doc.org/en/master/),\n [sphinx-autodoc-typehints](https://pypi.org/project/sphinx-autodoc-typehints/),\n or the Python API dependencies are not available.\n\n\n### Contributing Markdown Documentation\n\nTo add a new markdown document to the documentation:\n\n1. Create the new document as a child of `/doc`.\n - File names start with `gtirb`.\n - File extension is `.md`.\n - Use github markdown syntax.\n - Wrap your markdown documents at 80 columns.\n\n2. Edit `/doc/general/Doxyfile.in` to add the basename of your new markdown\n document to the `INPUT` rule setting.\n\n3. Edit `/doc/general/CMakeLists.txt` to add your new markdown document\n to `MDFILES_IN`. Ordering is not important.\n\n4. Integrate your new markdown document into the documentation, either\n by linking to it from an existing page or by updating\n `/doc/general/DoxygenLayout.xml` to add an entry to the **More Information**\n tab.\n\n5. [Build the documentation](#building-documentation) and check that\n your new page is present and rendered correctly.\n - If it is not rendered correctly, you may need to add a new\n preprocessing step to `doc/general/preprocmd.py` to rewrite the\n corresponding github-style markdown into something Doxygen\n can handle correctly.\n\n### Graphviz\n\n- File names start with `gtirb`.\n- The color palette is `black`, `lightblue`, `cornflowerblue`, and `coral`.\n- Render `.dot` files to the same file name with a `.png` extension.\n\t* Example: `dot -Tpng gtirbScope.dot > gtirbScope.png`\n- Use the `arial` font.\n\n### Python\n\nFor the Python API, [Sphinx](https://www.sphinx-doc.org/en/master/)\nand [related plugins](https://pypi.org/project/sphinx-autodoc-typehints/)\nare required. To install these via [pip](https://pip.pypa.io/en/stable/), run:\n\n```bash\npip3 install sphinx sphinx-autodoc-typehints\n```\n\nYou will also need all the dependencies of the GTIRB Python API\nitself. If you haven't already installed the Python API (and don't\nwant to do so now) you can install just its dependencies as follows.\n\n```bash\ncd /build/python\npython3 setup.py egg_info\npip3 install -r gtirb.egg-info/requires.txt\n```\n\n### Common Lisp\n\nFor the Common Lisp API, [simpler-documentation-template (SDT)](https://github.com/eschulte/simpler-documentation-template)\nis required. This package should automatically be downloaded via the build process;\nsee `cl/README.md` for details on how to prepare the Common Lisp API.\n" }, { "path": "FAQ.md", "content": "Frequently Asked Questions\n--------------------------\n\n- [I get compiler errors when I try to compile programs using GTIRB. How can I make them go away?](#compiler-errors)\n\n- [Linking error with \"undefined reference\" to gtirb::](#linking-error-with-undefined-reference-to-gtirb)\n\n#### Compiler Errors\n\n__Q: I get compiler errors when I try to compile programs using GTIRB. How can I make them go away?__\n\nA: GTIRB requires C++17, including the C++17 standard library. If your\ncompiler does not use C++17 by default, you will need to explicitly\nspecify it when compiling programs that use GTIRB.\n\nFor example:\n```\ng++ --std=c++17 my_gtirb_program.cpp -lgtirb -o my_gtirb_program\n```\n\n\n#### Linking error with \"undefined reference\" to gtirb\n\n__Q: I get linker errors when I try to compile and link programs using GTIRB. How can I make them go away?__\n\nA: This isn't GTIRB specific, but if you place the `-lgtirb` on your\ncompilation line *before* the source file the linker will sometimes\nthrow away the symbols from the GTIRB library which it doesn't think\nit needs (and if it hasn't read your source yet it won't think it\nneeds much). So if for example,\n\n```\ng++ --std=c++17 -lgtirb my_gtirb_program.cpp\n```\n\ndoesn't work for you, then try this instead.\n\n```\ng++ --std=c++17 my_gtirb_program.cpp -lgtirb\n```\n" }, { "path": "LICENSE.txt", "content": "==============================================================================\nGTIRB is under the MIT License:\n==============================================================================\n\nMIT License\n\nCopyright (c) 2018 GrammaTech, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n==============================================================================\nSoftware from third parties included in GTIRB:\n==============================================================================\n\nGTIRB contains third party software which is under different license terms.\nAll such code will be identified clearly using at least one of two mechanisms:\n\n1) It will be in a separate directory tree with its own `LICENSE.txt` or\n `LICENSE` file at the top containing the specific license and restrictions\n which apply to that software, or\n2) It will contain specific license and restriction terms at the top of every\n file.\n\n==============================================================================\nApache License v2.0 with LLVM Exceptions:\n==============================================================================\n\n Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\n END OF TERMS AND CONDITIONS\n\n APPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don't include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\n Copyright [yyyy] [name of copyright owner]\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.\n\n\n---- LLVM Exceptions to the Apache 2.0 License ----\n\nAs an exception, if, as a result of your compiling your source code, portions\nof this Software are embedded into an Object form of such source code, you\nmay redistribute such embedded portions in such Object form without complying\nwith the conditions of Sections 4(a), 4(b) and 4(d) of the License.\n\nIn addition, if you combine or link compiled forms of this Software with\nsoftware that is licensed under the GPLv2 (\"Combined Software\") and if a\ncourt of competent jurisdiction determines that the patent provision (Section\n3), the indemnity provision (Section 9) or other Section of the License\nconflicts with the conditions of the GPLv2, you may retroactively and\nprospectively choose to deem waived or otherwise exclude such Section(s) of\nthe License, but only in their entirety and only with respect to the Combined\nSoftware.\n\n==============================================================================\nUniversity of Illinois Open Source License:\n==============================================================================\nUniversity of Illinois/NCSA\nOpen Source License\n\nCopyright (c) 2003-2019 University of Illinois at Urbana-Champaign.\nAll rights reserved.\n\nDeveloped by:\n\n LLVM Team\n\n University of Illinois at Urbana-Champaign\n\n http://llvm.org\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the \"Software\"), to deal with\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies\nof the Software, and to permit persons to whom the Software is furnished to do\nso, subject to the following conditions:\n\n * Redistributions of source code must retain the above copyright notice,\n this list of conditions and the following disclaimers.\n\n * Redistributions in binary form must reproduce the above copyright notice,\n this list of conditions and the following disclaimers in the\n documentation and/or other materials provided with the distribution.\n\n * Neither the names of the LLVM Team, University of Illinois at\n Urbana-Champaign, nor the names of its contributors may be used to\n endorse or promote products derived from this Software without specific\n prior written permission.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\nFOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nCONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE\nSOFTWARE.\n" }, { "path": "Macros.cmake", "content": "macro(IMPL_GTIRB_ADD_LINKER_FLAG flag)\n if(NOT ${CMAKE_EXE_LINKER_FLAGS} MATCHES \"(${flag}.*)\")\n set(CMAKE_EXE_LINKER_FLAGS\n \"${CMAKE_EXE_LINKER_FLAGS} ${flag}\"\n CACHE STRING \"Linker Flags\" FORCE\n )\n endif()\n\n if(NOT ${CMAKE_SHARED_LINKER_FLAGS} MATCHES \"(${flag}.*)\")\n set(CMAKE_SHARED_LINKER_FLAGS\n \"${CMAKE_SHARED_LINKER_FLAGS} ${flag}\"\n CACHE STRING \"Linker Flags\" FORCE\n )\n endif()\nendmacro()\n\nmacro(GTIRB_ADD_MSVC_LINKER_FLAG flag)\n if(MSVC)\n impl_gtirb_add_linker_flag(${flag})\n endif()\nendmacro()\n\nmacro(GTIRB_ADD_GCC_LINKER_FLAG flag)\n if(CMAKE_COMPILER_IS_GNUCXX)\n impl_gtirb_add_linker_flag(${flag})\n endif()\nendmacro()\n\nmacro(GTIRB_ADD_CLANG_LINKER_FLAG flag)\n if(${CMAKE_CXX_COMPILER_ID} STREQUAL Clang)\n impl_gtirb_add_linker_flag(${flag})\n endif()\nendmacro()\n\nmacro(GTIRB_ADD_LIBRARY)\n add_library(\n ${PROJECT_NAME} ${${PROJECT_NAME}_H} ${${PROJECT_NAME}_SRC}\n ${${PROJECT_NAME}_PROTO}\n )\n\n set_target_properties(${PROJECT_NAME} PROPERTIES FOLDER \"gtirb\")\nendmacro()\n\nmacro(GTIRB_ADD_LIBRARY_STATIC)\n add_library(\n ${PROJECT_NAME} STATIC ${${PROJECT_NAME}_H} ${${PROJECT_NAME}_SRC}\n )\n\n set_target_properties(${PROJECT_NAME} PROPERTIES FOLDER \"gtirb\")\nendmacro()\n\nmacro(GTIRB_ADD_LIBRARY_HEADERONLY)\n add_library(${PROJECT_NAME} INTERFACE)\n target_include_directories(\n ${PROJECT_NAME} INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}\n )\nendmacro()\n\nmacro(GTIRB_ADD_EXECUTABLE)\n add_executable(${PROJECT_NAME} ${${PROJECT_NAME}_H} ${${PROJECT_NAME}_SRC})\n set_target_properties(${PROJECT_NAME} PROPERTIES FOLDER \"gtirb/applications\")\nendmacro()\n\nmacro(GTIRB_ADD_EXECUTABLE_GTEST)\n add_executable(${PROJECT_NAME} ${${PROJECT_NAME}_H} ${${PROJECT_NAME}_SRC})\n\n add_test(NAME ${PROJECT_NAME} COMMAND ${PROJECT_NAME})\n set_target_properties(${PROJECT_NAME} PROPERTIES FOLDER \"gtirb/test\")\nendmacro()\n\nmacro(GTIRB_GET_ALL_SUBDIRS result curdir)\n file(\n GLOB children\n RELATIVE ${curdir}\n ${curdir}/*\n )\n set(dirlist \"\")\n foreach(child ${children})\n if(IS_DIRECTORY ${curdir}/${child})\n list(APPEND dirlist ${child})\n endif()\n endforeach()\n set(${result} ${dirlist})\nendmacro()\n\nmacro(GTIRB_ADD_ALL_SUBDIRS)\n gtirb_get_all_subdirs(SUBDIRS ${CMAKE_CURRENT_SOURCE_DIR})\n foreach(subdir ${SUBDIRS})\n add_subdirectory(${subdir})\n endforeach()\nendmacro()\n\n# Provide a vaguely consistent interface to find a Python 3 interpreter. Just\n# use FindPython3 if it exists, but fall back to looking for the interpreter\n# program if we have to.\nif(${CMAKE_VERSION} VERSION_GREATER_EQUAL \"3.12\")\n macro(GTIRB_FIND_PYTHON)\n find_package(Python3 REQUIRED COMPONENTS Interpreter)\n if(Python3_EXECUTABLE)\n set(PYTHON ${Python3_EXECUTABLE})\n endif()\n endmacro()\nelse()\n macro(GTIRB_FIND_PYTHON)\n find_program(PYTHON NAMES python3 python py)\n if(PYTHON)\n execute_process(\n COMMAND \"${PYTHON}\" --version OUTPUT_VARIABLE Python3_VERSION\n )\n string(REPLACE \"Python \" \"\" Python3_VERSION \"${Python3_VERSION}\")\n if(\"${Python3_VERSION}\" VERSION_LESS 3)\n unset(PYTHON)\n unset(Python3_VERSION)\n endif()\n endif()\n endmacro()\nendif()\n" }, { "path": "PROTOBUF.md", "content": "Using Serialized GTIRB Data\n===========================\n\n> Note that for language with GTIRB APIs (at least C++, Python, Common\n> Lisp) using the GTIRB API is preferrable to manipulating protobuf\n> directly.\n\nGTIRB uses a serialized format that consists of an 8-byte signature\nfollowed by serialized [protobuf](https://github.com/google/protobuf/wiki)\ndata. The protobuf data allows for exploration and manipulation in the\nlanguage of your choice.\nThe [Google protocol buffers](https://developers.google.com/protocol-buffers/)\nhomepage lists the languages in which protocol buffers can be used directly;\nusers of other languages can convert the protobuf-formatted data to\nJSON format and then use the JSON data in their applications. In the\nfuture we intend to define a standard JSON schema for GTIRB.\n\nThe 8-byte signature that prefixes the protobuf data includes both\nGTIRB's magic number and the version fot GTIRB's protobuf specification\nthat is in use. The layout is as follows:\n\n - Bytes 0-4 contain the ASCII characters: `GTIRB`.\n - Bytes 5-6 are considered reserved for future use and should be 0.\n - Byte 7 contains the GTIRB protobuf spec version in use.\n\nDirectory `gtirb/src/proto` contains the protocol buffer message type\ndefinitions for GTIRB. You can inspect these `.proto` files to\ndetermine the structure of the various GTIRB message types. The\ntop-level message type is `IR`.\n\n\n- [General Guidelines](#general-guidelines)\n- [Python Applications](#python-applications)\n- [Java Applications](#java-applications)\n\n\n# General Guidelines\n\nIf you have not used protocol buffers before, there are several useful\nresources available at\nhttps://developers.google.com/protocol-buffers/, including an\ninstallation guide and a tutorial.\n\nIn general, writing an application to use GTIRB data in protocol\nbuffer format will involve the following steps.\n\n1. Install the protocol buffer compiler (`protoc`) from\n https://github.com/protocolbuffers/protobuf/releases, if you\n haven't already done so.\n\n2. Install any required protocol buffer library or libraries for the\n programming language you are using.\n\n3. Invoke the protocol buffer compiler on the `.proto` files in\n `gtirb/src/proto/` to generate code in the language you wish to use.\n\n4. Write your application, importing/including the file or files you\n generated in step 3.\n\nThe [Protocol Buffers API\nReference](https://developers.google.com/protocol-buffers/docs/reference/overview)\nprovides language-specific instructions for the various supported\nprogramming languages, along with links to information for cases where\nsupport is provided by third-party plug-ins.\n\n\n# Python Applications\n\nTo create a Python application that uses serialized GTIRB data, do the\nfollowing.\n\n1. Install the protocol buffer compiler (`protoc`).\n\n2. Install the Python protobuf library, if you haven't already done so.\n\n $ pip install protobuf\n\n3. Generate Python message definitions in a dedicated directory (for\n example, `python/`).\n\n $ mkdir -p python\n $ for f in src/proto/*.proto; do\n protoc -Isrc/proto --python_out=python $f\n done\n\n This will create a number of files with names of the form\n `_pb2.py` in the `python/` subdirectory of your working\n directory: one for each `.proto` in src/proto/, including\n `IR_pb2.py`.\n\n4. Write your application. Make sure that it imports `IR_pb2`, or the\n parts of it that you require.\n\n5. Run your application, making sure that the directory containing\n your message definitions is in the `PYTHONPATH`.\n\n## Python Examples\n\nDirectory `gtirb/doc/examples` contains several example Python scripts\nthat use protocol buffers to explore serialized GTIRB data.\n- [cfg-paths.py](doc/examples/cfg-paths.py)\n- [data-symbols.py](doc/examples/data-symbols.py)\n\n\n# Java Applications\n\n\nTo create a Java application that uses serialized GTIRB data, do the\nfollowing.\n\n1. Install the protocol buffer compiler (`protoc`).\n\n2. Download the `protobuf` Java runtime from\n [https://mvnrepository.com/artifact/com.google.protobuf/protobuf-java](https://mvnrepository.com/artifact/com.google.protobuf/protobuf-java)\n and save it somewhere suitable.\n\n3. Generate Java message definitions in a dedicated directory (for example,\n `java/`).\n\n $ mkdir -p java\n $ for f in src/proto/*.proto; do\n protoc -Isrc/proto --java_out=java $f\n done\n\n This will create a subdirectory `java/proto/', containing a number\n of files with names of the form `OuterClass.java`: one for each\n `.proto` in `src/proto/`.\n\n4. Compile the Java message definitions, making sure the `protobuf`\n Java runtime `.jar` file is in your `CLASSPATH`.\n\n $ mkdir -p java/classfiles\n $ CLASSPATH= \\\n javac -d java/classfiles java/proto/*.java\n\n (If you want to build a `.jar` file to combine all these\n `.class` files, do so at this stage.)\n\n5. Write your application. Make sure that it imports all the classes\n you need from the `proto` package.\n\n6. Compile and run your application, making sure that your CLASSPATH\n contains both the `protobuf` Java runtime `.jar` file and the\n location of the your compiled message definition classes.\n\n\n## Java Examples\n\nDirectory `gtirb/doc/examples` contains several example Java programs\nthat use protocol buffers to explore serialized GTIRB data.\n\n- [datasymbols.java](doc/examples/datasymbols.java)\n" }, { "path": "README.md", "content": "# GTIRB\n\nThe GrammaTech Intermediate Representation for Binaries (GTIRB) is a\nmachine code analysis and rewriting data structure. It is intended to\nfacilitate the communication of binary IR between programs performing\nbinary disassembly, analysis, transformation, and pretty printing.\nGTIRB is modeled on LLVM-IR, and seeks to serve a similar\nfunctionality of encouraging communication and interoperability\nbetween tools.\n\nThe remainder of this file describes various aspects of GTIRB:\n- [Structure](#structure)\n- [Installing](#installing)\n- [Building](#building)\n- [Usage](#usage)\n\n# Structure\n\nGTIRB has the following structure. Solid lines denote inheritance.\nDotted lines denote reference by UUID.\n\n![GTIRB Data Structure](.gtirb.svg)\n\n## IR\n\nAn instance of GTIRB may include multiple modules (`Module`) which\nrepresent loadable objects such as executables or libraries, an\ninter-procedural control flow graph (`IPCFG`), and Auxiliary Data tables\n(`AuxData`) which can hold arbitrary analysis results in user-defined\nformats which can easily reference other elements of the IR. Each\nmodule holds information such as symbols (`Symbol`) and sections which\nthemselves hold the actual bytes and data and code blocks of the\nmodule. The CFG consists of basic blocks (`Block`) and control flow\nedges between these blocks. Each data or code block references a\nrange of bytes in a byte interval (`ByteInterval`). A section may\nhold one large byte interval holding all blocks---if the relative\npositions of blocks in that section are defined---or may hold one byte\ninterval per block---if the relative positions of blocks is not\ndefined, e.g. for the code blocks in the `.text` section during\nprogram rewriting. Each symbol holds a pointer to the block or datum\nit references.\n\n\n## Instructions\n\nGTIRB explicitly does NOT represent instructions or instruction\nsemantics but does provide symbolic operand information and access to\nthe bytes. There are many *intermediate languages* (IL)s for\nrepresentation of instruction semantics (e.g., [BAP][]'s [BIL][],\n[Angr][]'s [Vex][], or [Ghidra][]'s P-code). GTIRB works with these\nor any other IL by storing instructions generally and efficiently as\n*raw machine-code bytes* and separately storing the symbolic and\ncontrol flow information. The popular [Capstone][]/[Keystone][]\ndecoder/encoder provide an excellent option to read and write\ninstructions from/to GTIRB's machine-code byte representation without\ncommitting to any particular semantic IL. By supporting multiple ILs\nand separate storage of analysis results in auxiliary data tables\nGTIRB enables collaboration between independent binary analysis and\nrewriting teams and tools.\n\n[BAP]: https://github.com/BinaryAnalysisPlatform/bap\n[BIL]: https://github.com/BinaryAnalysisPlatform/bil/releases/download/v0.1/bil.pdf\n[Angr]: http://angr.io\n[Vex]: https://github.com/angr/pyvex\n[Ghidra]: https://www.nsa.gov/resources/everyone/ghidra/\n[Capstone]: https://www.capstone-engine.org\n[Keystone]: https://www.keystone-engine.org\n\n\n## Auxiliary Data\n\nGTIRB provides for the sharing of additional information,\ne.g. analysis results, in the form of `AuxData` objects. These can\nstore maps and vectors of basic GTIRB types in a portable way. The\n[GTIRB manual][] describes the structure for common types of auxiliary\ndata such as function boundary information, type information, or\nresults of common analyses in [Standard AuxData Schemata][].\n\n[GTIRB manual]: https://grammatech.github.io/gtirb/\n[Standard AuxData Schemata]: https://grammatech.github.io/gtirb/md__aux_data.html\n\n\n## UUIDs\n\nEvery element of GTIRB---e.g., modules (`Module`), symbols (`Symbol`),\nand blocks (`Block`)---has a universally unique identifier (UUID).\nUUIDs allow both first-class IR components and AuxData tables to\nreference elements of the IR.\n\nInstructions and symbolic operands can be addressed by the class\n`Offset` which encapsulates a UUID (that refers to the instruction's\nblock) and an offset.\n\n\n# Installing\n\nPackages currently exist for easily installing GTIRB (and attendant\ntooling including the [ddisasm][] disassembler and [gtirb-pprinter][]\npretty printer) on Windows, and Ubuntu 20. See below for\ninstructions. Additionally, a public Docker image exists at\n[grammatech/ddisasm][] with all of these tools installed. GTIRB is\nversioned with Major.Minor.Patch versioning where Major version\nincrements will require significant source changes but should be very\nrare, Minor version increments may require small source changes, and\nPatch version increments shouldn't break any downstream builds. We do\nnot yet provide ABI compatibility across any version changes.\n\n[ddisasm]: https://github.com/GrammaTech/ddisasm\n[gtirb-pprinter]: https://github.com/GrammaTech/gtirb-pprinter\n[grammatech/ddisasm]: https://hub.docker.com/r/grammatech/ddisasm\n\n\n## Python API\n\nThe latest stable GTIRB Python API may be installed from PyPI using pip:\n\n```sh\npip install gtirb\n```\n\nThe latest unstable version of the Python API can be installed from a\nprebuilt wheel:\n\n```sh\npip install https://download.grammatech.com/gtirb/files/python/gtirb-0.dev-py3-none-any.whl\n```\n\nIt is critical that the choice of a `stable` or `unstable` package matches the\ninstalled ddisasm and gtirb-pprinter packages.\n\n## Windows\n\nWindows releases are packaged as .zip files and are available at\nhttps://download.grammatech.com/gtirb/files/windows-release/.\n\n## Ubuntu\n\nPackages for Ubuntu 20 are available in the GTIRB apt repository and may\nbe installed per the following instructions.\n\nFirst, add GrammaTech's APT key.\n```sh\nwget -O - https://download.grammatech.com/gtirb/files/apt-repo/conf/apt.gpg.key | apt-key add -\n```\n\nNext update your sources.list file.\n```sh\necho \"deb [arch=amd64] https://download.grammatech.com/gtirb/files/apt-repo [distribution] [component]\"| sudo tee -a /etc/apt/sources.list\n```\nWhere:\n- `[distribution]` is `focal` (currently, only Ubuntu 20 packages are available)\n- `[component]` is either `stable`, which holds the last versioned release, or\n`unstable`, which holds the HEAD of the repository.\n\nFinally update your package database and install the core GTIRB tools:\n```sh\nsudo apt-get update\nsudo apt-get install gtirb-pprinter ddisasm\n```\n\n**Warning**: Stable versions gtirb-2.0.0, gtirb-pprinter-2.1.0, ddisasm-1.8.0\nand OLDER rely on metapackages which cause conflicts if you try `apt-get upgrade`\n(see https://github.com/GrammaTech/gtirb/issues/63). In this case,\nuninstall and reinstall the packages you got from the GTIRB repository. You\nmay need to use `dpkg --remove` to remove the metapackages (e.g. `ddisasm`)\nbefore removing the concrete versioned packages (e.g. `ddisasm-1.5.1`).\nNEWER stable versions no longer rely on metapackages and can be upgraded\nwithout problems.\n\n# Building\n\nGTIRB's C++ API should successfully build in 64-bits with GCC, Clang,\nand Visual Studio compilers supporting at least C++17. GTIRB uses\nCMake which must be installed with at least version 3.10.\n\nThe common build process looks like this:\n```sh\nmkdir build\ncd build\n# Note: You may wish to add some -D arguments to the next command. See below.\ncmake \ncmake --build .\n# Run the test suite.\nctest\n```\n\nFor customizing the GTIRB build, you can get a list of customization options by\nnavigating to your build directory and running:\n\n```sh\ncmake -LH\n```\n\n## Requirements\n\nTo build and install GTIRB, the following requirements should be installed:\n\n- [CMake][], version 3.10.0 or higher.\n - Ubuntu 18 provides this version via the APT package `cmake`.\n - Ubuntu 16 and earlier provide out of date versions; build from\n source on those versions.\n- [Protobuf][], version\n 3.0.0 or later.\n - Ubuntu 18 provides this version via the APT packages\n `libprotobuf-dev` and `protobuf-compiler`.\n - Ubuntu 16 and earlier provide out of date versions; build from\n source on those versions.\n- Boost [(non-standard Ubuntu package from launchpad.net)][], version 1.68 or later.\n - Ubuntu 18 only has version 1.65 in the standard repository. See Ubuntu instructions above.\n\n[CMake]: https://cmake.org/\n[Protobuf]: https://developers.google.com/protocol-buffers/\n[(non-standard Ubuntu package from launchpad.net)]: https://launchpad.net/~mhier/+archive/ubuntu/libboost-latest\n\n\n# Usage\n\nGTIRB is designed to be serialized using [Google protocol buffers][]\n(i.e., [protobuf][]), enabling [easy and efficient use from any\nprogramming language](#using-serialized-gtirb-data).\n\nGTIRB may also be used through a dedicated API implemented in multiple\nlanguages. The APIs provide efficient data structures suitable for use\nby binary analysis and rewriting applications; see\n[below](#gtirb-api-implementations) for details.\n\n[Google protocol buffers]: https://developers.google.com/protocol-buffers/\n[protobuf]: https://github.com/google/protobuf/wiki\n\n\n## Using Serialized GTIRB Data\n\nGTIRB uses a serialized format that consists of an 8-byte signature\nfollowed by serialized [protobuf][] data. The protobuf data allows\nfor exploration and manipulation in the language of your choice.\nThe [Google protocol buffers][] homepage lists the languages in which\nprotocol buffers can be used directly; users of other languages can\nconvert the protobuf-formatted data to JSON format and then use the\nJSON data in their applications.\n\nThe `proto` directory in this repository contains the protocol buffer\nmessage type definitions for GTIRB. You can inspect these `.proto`\nfiles to determine the structure of the various GTIRB message\ntypes. The top-level message type is `IR`.\n\nFor more details, see [Using Serialized GTIRB Data](PROTOBUF.md).\n\n\n## GTIRB API Implementations\n\nThe GTIRB API is currently available in C++, Python, and Common Lisp.\nThere is a *partial* Java API which is not ready for external use.\nFor language-independent API information, see [GTIRB\nComponents](doc/general/ComponentsIndex.md). For information about the\ndifferent API implementations, see:\n\n - [C++ API](doc/cpp/README.md)\n - [Python API](python/README.md)\n - [Common Lisp API](cl/README.md)\n - Java API **incomplete**\n" }, { "path": "cl/CMakeLists.txt", "content": "file(GLOB CL_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/*.lisp\n ${CMAKE_CURRENT_SOURCE_DIR}/*.asd\n)\n\nset(CL_EXECUTABLE_STEMS dot update)\n\nforeach(CL_EXECUTABLE_STEM ${CL_EXECUTABLE_STEMS})\n set(CL_EXECUTABLE ${CMAKE_CURRENT_BINARY_DIR}/gtirb-${CL_EXECUTABLE_STEM})\n list(APPEND CL_EXECUTABLES ${CL_EXECUTABLE})\n\n add_custom_command(\n OUTPUT ${CL_EXECUTABLE}\n DEPENDS ${CL_SOURCES} ${PROTO_FILES}\n WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}\n COMMAND\n ${LISP} --noinform --dynamic-space-size 16384 --no-userinit --no-sysinit\n --disable-debugger --load ${QUICKLISP}/setup.lisp --eval\n \"(asdf:initialize-source-registry `(:source-registry (:tree \\\"${CMAKE_CURRENT_SOURCE_DIR}\\\") :inherit-configuration))\"\n --eval \"(ql:quickload :gtirb/${CL_EXECUTABLE_STEM})\" --eval\n \"(setf uiop/image::*lisp-interaction* nil)\" --eval\n \"(asdf:make :gtirb/run-${CL_EXECUTABLE_STEM} :type :program :monolithic t)\"\n --eval \"(uiop/image:quit)\"\n COMMAND ${CMAKE_COMMAND} -E copy gtirb-${CL_EXECUTABLE_STEM}\n ${CMAKE_CURRENT_BINARY_DIR}\n COMMAND ${CMAKE_COMMAND} -E remove gtirb-${CL_EXECUTABLE_STEM}\n VERBATIM\n )\nendforeach(CL_EXECUTABLE_STEM)\n\nadd_custom_target(clgtirb ALL DEPENDS ${CL_EXECUTABLES})\n\nif(GTIRB_ENABLE_TESTS)\n add_test(\n NAME testgtirbcl\n COMMAND\n ${LISP} --noinform --dynamic-space-size 16384 --no-userinit --no-sysinit\n --disable-debugger --load \"${QUICKLISP}/setup.lisp\" --eval\n \"(asdf:initialize-source-registry `(:source-registry (:tree \\\"${CMAKE_CURRENT_SOURCE_DIR}\\\") :inherit-configuration))\"\n --eval \"(ql:quickload :gtirb/test)\" --eval \"(gtirb/test:batch-test)\"\n WORKING_DIRECTORY \"${CMAKE_CURRENT_SOURCE_DIR}/\"\n )\nendif()\n" }, { "path": "cl/README.md", "content": "Common Lisp library for GTIRB\n=============================\n\nThe Common Lisp API for GrammaTech's IR for Binaries (GTIRB). GTIRB\nis a data structure designed to support the analysis and rewriting of\nbinary executables. There are a number of tools that produce, process\nand consume GTIRB. See the following for more information on GTIRB:\n- [https://github.com/grammatech/gtirb](https://github.com/grammatech/gtirb) the main GTIRB source repository.\n- [https://grammatech.github.io/gtirb/](https://grammatech.github.io/gtirb/) the GTIRB manual repository.\n- [https://arxiv.org/abs/1907.02859](https://arxiv.org/abs/1907.02859) a white-paper describing the design goals of GTIRB.\n- [https://github.com/grammatech/ddisasm](https://github.com/grammatech/ddisasm) a very high performance reassembleable disassembler producing GTIRB.\n- [https://github.com/grammatech/gtirb-pprinter](https://github.com/grammatech/gtirb-pprinter) a pretty printer from GTIRB to assembler.\n\n## Requirements and Installation\nHopefully, eventually, it will be possible to install everything by\n(1) installing\n[Protobuf](https://developers.google.com/protocol-buffers/), version\n3.7.0 or later, and then (2) installing this Common Lisp GTIRB library\nwith QuickLisp `(ql:quickload :gtirb)`.\n\nWe're a ways away from that currently. So after you've installed\nProtobuf, you should clone and install the Common Lisp `PROTOBUF`\npackage manually according to the instructions at\n[https://github.com/brown/protobuf](https://github.com/brown/protobuf)\nensuring that the `protoc-gen-lisp` executable has been built and is\non your path. At that point you should be able to load the GTIRB\npackage.\n\n## Usage\nThe Common Lisp API attempts to provide access to the underlying GTIRB\ndata-structure described above in idiomatic common lisp. The main\nProtobuf data structures are wrapped in CLOS objects. All fields are\nmodifiable with `setf`. Invariant are maintained automatically by the\nAPI, e.g. using `:around` methods.\n\nIn some cases accessors are provided beyond the fields directly\npresent in the Protobuf. For example, every GTIRB element has a UUID\n(which supports referencing elements from AuxData tables). The Common\nLisp API provides uniform access to any element through the `get-uuid`\nmethod which operates similarly to `gethash` only it may be called on\nany top-level GTIRB `IR` object (which itself maintains a hash of\nevery contained element by UUID).\n\nThe GTIRB CFG is represented as a graph using the Common Lisp graph\nlibrary from\n[https://github.com/eschulte/graph](https://github.com/eschulte/graph).\nThis simple representation should promote easy exploration and\nmodification of the control flow graph, and the many graph analysis\nfunctions defined in that library may be directly applied to the CFG.\nEvery node of the graph holds the UUID for a code block.\n\nThe bytes of any code and data block may be accessed by calling the\n`bytes` method, which provides directly access to the bytes of the\nblock's `byte-interval`.\n\n### Example Usage\nSee the test suite for a large number of basic usage examples.\nHowever, the following gives a simple usage example.\n\n1. From the command-line. Use the datalog disassembler `ddisasm` to\n disassemble the `ls` executable into a GTIRB instance.\n\n ddisasm --ir $(which ls) /tmp/ls.gtirb\n\n2. From the Common Lisp REPL. Load the GTIRB API, and then load the\n GTIRB instance created in step (1) into a common lisp GTIRB object.\n\n (ql:quickload :gtirb)\n (use-package :gtirb)\n (defparameter ls (read-gtirb \"/tmp/ls.gtirb\"))\n\n3. At this point you can explore the CFG, perform analyses, or even\n modify the contents of the GTIRB object. Results of analyses may\n be saved into new AuxData tables which become part of the GTIRB\n object for later use by other sessions or by other tools\n potentially written in other languages.\n\n ;; Do stuff with the GTIRB, maybe make changes.\n\n4. Finally, the resulting GTIRB object may be written back to the\n file system.\n\n (write-gtirb ls \"/tmp/ls-modified.gtirb\")\n\n5. At the command line. A new executable may be created from the\n modified gtirb file using the `gtirb-pprinter`.\n\n gtirb-pprinter --ir /tmp/ls-modified.gtirb --binary /tmp/ls-modified\n" }, { "path": "cl/dot.lisp", "content": "(defpackage :gtirb/dot\n (:use :common-lisp :alexandria :graph :graph/dot :gtirb\n :command-line-arguments\n :named-readtables :curry-compose-reader-macros)\n (:import-from :uiop :nest)\n (:import-from :uiop/image :quit)\n (:shadowing-import-from :proto-v0 :ir)\n (:shadowing-import-from :gtirb :symbol)\n (:export :to-dot :to-dot-file))\n(in-package :gtirb/dot)\n(in-readtable :curry-compose-reader-macros)\n\n(defun dot-edge-label (graph edge)\n (let ((obj (edge-value graph edge)))\n (format nil \"\\\"~a[~:[U~;C~]:~:[I~;D~]]\\\"\"\n (edge-type obj) (conditional obj) (direct obj))))\n\n(defmethod to-dot ((obj gtirb) &rest rest)\n \"Write the CFG of MODULE to the Graphviz graphing language.\"\n (apply #'to-dot (cfg obj)\n :edge-attrs (list (cons :label {dot-edge-label (cfg obj)}))\n rest))\n\n(eval-when (:compile-toplevel :load-toplevel :execute)\n (defparameter +udpate-args+\n '(((\"help\" #\\h #\\?) :type boolean :optional t\n :documentation \"display help output\"))))\n\n;;; NOTE: When Quicklisp updates graph to the latest this can be removed.\n(defmethod to-dot-file\n ((object t) path &key attributes node-attrs edge-attrs\n subgraphs ranks)\n (with-open-file (out path :direction :output :if-exists :supersede)\n (to-dot object :stream out :attributes attributes :node-attrs node-attrs\n :edge-attrs edge-attrs :subgraphs subgraphs :ranks ranks)))\n\n(define-command dot (gtirb-file dot-file &spec +udpate-args+)\n \"Write first GTIRB module in GTIRB-FILE to DOT-FILE.\" \"\"\n (when help (show-help-for-dot) (quit))\n (to-dot-file (read-gtirb gtirb-file) dot-file))\n" }, { "path": "cl/gtirb.asd", "content": "(defsystem \"gtirb\"\n :name \"gtirb\"\n :author \"GrammaTech\"\n :licence \"MIT\"\n :description \"Common Lisp library for GTIRB\"\n :long-description \"A Common Lisp front end to the GrammaTech\n Intermediate Representation for Bianries (GTIRB). GTIRB is\n serialized using Google's protocol buffers. This library wraps the\n raw protocol buffer serialization with a more Lispy interface.\"\n :depends-on (:gtirb/gtirb)\n :class :package-inferred-system\n :defsystem-depends-on (:asdf-package-system :protobuf)\n :in-order-to ((test-op (load-op \"gtirb/test\")))\n :perform (test-op (o c) (symbol-call :gtirb/test '#:test)))\n\n(defsystem \"proto-v0\"\n :name \"proto-v0\"\n :description \"Common Lisp interface to (old V0) GTIRB protobuf files\"\n :author \"GrammaTech\"\n :license \"MIT\"\n :defsystem-depends-on (:protobuf)\n :components\n ((:static-file \"README.md\")\n ;; See the protobuf defsystem extension for how the gtirb.proto\n ;; file is loaded into Lisp. https://github.com/brown/protobuf\n (:module proto\n :pathname \"../proto/v0/\"\n :components\n ((:protobuf-source-file \"AuxDataContainer\")\n (:protobuf-source-file \"CFG\")\n (:protobuf-source-file \"Section\")\n (:protobuf-source-file \"Offset\")\n (:protobuf-source-file \"IR\")\n (:protobuf-source-file \"ByteMap\")\n (:protobuf-source-file \"ProxyBlock\")\n (:protobuf-source-file \"AuxData\")\n (:protobuf-source-file \"Module\")\n (:protobuf-source-file \"DataObject\")\n (:protobuf-source-file \"ImageByteMap\")\n (:protobuf-source-file \"SymbolicExpression\")\n (:protobuf-source-file \"Symbol\")\n (:protobuf-source-file \"Block\")))))\n\n(defsystem \"proto\"\n :name \"proto\"\n :description \"Common Lisp interface to GTIRB protobuf files\"\n :author \"GrammaTech\"\n :license \"MIT\"\n :defsystem-depends-on (:protobuf)\n :components\n ((:static-file \"README.md\")\n ;; See the protobuf defsystem extension for how the gtirb.proto\n ;; file is loaded into Lisp. https://github.com/brown/protobuf\n (:module proto\n :pathname \"../proto\"\n :components\n ((:protobuf-source-file \"AuxData\")\n (:protobuf-source-file \"ByteInterval\")\n (:protobuf-source-file \"CFG\")\n (:protobuf-source-file \"CodeBlock\")\n (:protobuf-source-file \"Offset\")\n (:protobuf-source-file \"DataBlock\")\n (:protobuf-source-file \"IR\")\n (:protobuf-source-file \"Module\")\n (:protobuf-source-file \"ProxyBlock\")\n (:protobuf-source-file \"Section\")\n (:protobuf-source-file \"Symbol\")\n (:protobuf-source-file \"SymbolicExpression\")))))\n\n(defsystem \"gtirb/run-validate\"\n :author \"GrammaTech\"\n :licence \"MIT\"\n :description \"Validate a GTIRB instance.\"\n :depends-on (gtirb/validate)\n :build-operation \"asdf:program-op\"\n :build-pathname \"gtirb-validate\"\n :entry-point \"gtirb/validate::run-validate-file\")\n\n(defsystem \"gtirb/run-update\"\n :author \"GrammaTech\"\n :licence \"MIT\"\n :description \"Convert between GTIRB protobuf versions.\"\n :depends-on (gtirb/update)\n :build-operation \"asdf:program-op\"\n :build-pathname \"gtirb-update\"\n :entry-point \"gtirb/update::run-update\")\n\n(defsystem \"gtirb/run-dot\"\n :author \"GrammaTech\"\n :licence \"MIT\"\n :description \"Write GTIRB to a dot graph.\"\n :depends-on (gtirb/dot)\n :build-operation \"asdf:program-op\"\n :build-pathname \"gtirb-dot\"\n :entry-point \"gtirb/dot::run-dot\")\n\n(register-system-packages \"proto\" '(:gtirb.proto))\n(register-system-packages \"cl-interval\" '(:interval))\n" }, { "path": "cl/gtirb.lisp", "content": "(defpackage :gtirb/gtirb\n (:nicknames :gtirb)\n (:use :common-lisp :alexandria :cl-ppcre :graph :trivia\n :trivial-utf-8\n :ieee-floats\n :gtirb/ranged\n :gtirb/utility\n :gtirb/version\n :named-readtables :curry-compose-reader-macros)\n (:shadow :symbol)\n (:import-from :gtirb.proto)\n (:import-from :trivial-package-local-nicknames :add-package-local-nickname)\n (:import-from :uiop :nest)\n (:import-from :cl-intbytes\n :int->octets\n :octets->int\n :octets->uint)\n (:export :read-gtirb\n :write-gtirb\n :is-equal-p\n :*is-equal-p-verbose-p*\n :gtirb-node\n :get-uuid\n :remove-uuid\n :at-address\n :on-address\n :address-range\n :uuid\n :update-proto\n;;; Classes and fields.\n :gtirb\n :ir\n :cfg\n :version\n ;; Module\n :module\n :name\n :binary-path\n :isa\n :file-format\n :byte-order\n :preferred-addr\n :rebase-delta\n :symbols\n :proxies\n :sections\n :aux-data\n :entry-point\n ;; Symbol\n :symbol\n :value\n :payload\n :at-end\n ;; Section\n :section\n :byte-intervals\n :flags\n ;; Byte-Interval\n :byte-interval\n :blocks\n :addressp\n :address\n :contents\n :size\n :truncate-contents\n :ignore\n ;; Symbolic expressions\n :symbolic-expressions\n :sym-addr-const\n :sym-addr-addr\n :scale\n :*preserve-symbolic-expressions*\n ;; Block\n :gtirb-block\n :gtirb-byte-block\n :code-block\n :data-block\n :decode-mode\n :bytes\n :offset\n ;; Edge-Label\n :edge-label\n :conditional\n :direct\n :edge-type\n ;; Aux-Data\n :aux-data-type\n :aux-data-data\n ;; gtirb\n :modules))\n(in-package :gtirb/gtirb)\n(in-readtable :curry-compose-reader-macros)\n\n(eval-when (:compile-toplevel :load-toplevel :execute)\n (add-package-local-nickname :proto :gtirb.proto))\n\n(defgeneric read-gtirb (source)\n (:documentation \"Read a protobuf serialized GTIRB instance from SOURCE.\")\n (:method ((path t))\n (make-instance 'gtirb :proto (read-proto 'proto:ir path))))\n\n(defmethod read-gtirb :around (source)\n \"Check the protobuf version.\"\n (let ((gtirb (call-next-method)))\n (unless (= protobuf-version (proto:version (proto gtirb)))\n (warn \"Protobuf version mismatch version ~a from ~a isn't expected ~a\"\n (proto:version (proto gtirb)) source protobuf-version))\n gtirb))\n\n(defun write-gtirb (gtirb path)\n \"Write a GTIRB IR object to PATH.\"\n (update-proto gtirb)\n (write-proto (proto gtirb) path))\n\n\f\n;;;; Class utilities.\n(defvar *is-equal-p-verbose-p* nil\n \"Compare equality verbosely in the `is-equal-p' function.\nThis may be useful to print contextual information when an equality\ncomparison fails for a large object with many nested objects.\")\n\n(defvar *is-equal-p-verbose-output-buffer* nil\n \"Buffer to hold output of is-equal-p verbose failure messages.\")\n\n(defvar *is-equal-p-verbose-output-length* 10\n \"Maximum length of output to show of `*is-equal-p-verbose-output-buffer*'.\")\n\n(defmacro compare-or-verbose (comparison left right &rest flags)\n `(or (,comparison ,left ,right ,@flags)\n (prog1 nil\n (when *is-equal-p-verbose-p*\n (push (format nil \"NOT ~S\" (list ',comparison ,left ,right))\n *is-equal-p-verbose-output-buffer*)))))\n\n(defun is-equal-p (left right)\n \"Return t if LEFT and RIGHT are equal.\nRecursively descend into any sub-structure. Custom recursive equality\npredicates are defined for common Common Lisp data structures as well\nas all GTIRB structures.\"\n (let ((*is-equal-p-verbose-output-buffer* nil))\n (let ((equalp (is-equal-p-internal left right)))\n (prog1 equalp\n (when (and (not equalp) *is-equal-p-verbose-p*)\n (format t \"~{~S~%~}\"\n (subseq *is-equal-p-verbose-output-buffer*\n 0 *is-equal-p-verbose-output-length*)))))))\n\n(defmethod is-equal-p-internal :around ((left t) (right t))\n (let ((equalp (call-next-method)))\n (when equalp (setf *is-equal-p-verbose-output-buffer* nil))\n equalp))\n\n(defgeneric is-equal-p-internal (left right)\n (:documentation \"Internal function called by `is-equal-p'.\")\n (:method ((left t) (right t))\n (compare-or-verbose equalp left right))\n (:method ((left number) (right number))\n (compare-or-verbose = left right))\n (:method ((left cl:symbol) (right cl:symbol))\n (compare-or-verbose eql left right))\n (:method ((left string) (right string))\n (compare-or-verbose string= left right))\n (:method ((left cons) (right cons))\n (if (and (proper-list-p left) (proper-list-p right))\n (compare-or-verbose set-equal left right :test #'is-equal-p-internal)\n (and (compare-or-verbose is-equal-p-internal (car left) (car right))\n (compare-or-verbose is-equal-p-internal (cdr left) (cdr right)))))\n (:method ((left hash-table) (right hash-table))\n (compare-or-verbose set-equal\n (hash-table-alist left) (hash-table-alist right)\n :test #'is-equal-p-internal))\n (:method ((left graph:digraph) (right graph:digraph))\n (and (compare-or-verbose set-equal (graph:nodes left) (graph:nodes right)\n :test #'is-equal-p-internal)\n (compare-or-verbose set-equal (graph:edges-w-values left)\n (graph:edges-w-values right)\n :test #'is-equal-p-internal))))\n\n(defclass gtirb-node () ()\n (:documentation \"Objects with a UUID contained in a GTIRB instance.\"))\n\n(defclass proto-backed (gtirb-node) ()\n (:documentation \"Objects which may be serialized to/from protobuf.\"))\n\n(defgeneric uuid (object)\n (:documentation \"Return the UUID for OBJECT as an integer.\")\n (:method ((obj proto-backed)) (uuid-to-integer (proto:uuid (proto obj)))))\n\n(defgeneric get-uuid (uuid object)\n (:documentation \"Get the referent of UUID in OBJECT.\"))\n\n(defgeneric remove-uuid (uuid object)\n (:documentation \"Remove the entry for UUID from OBJECT.\"))\n\n(defgeneric (setf get-uuid) (new uuid object)\n (:documentation \"Register REFERENT behind UUID in OBJECT.\"))\n\n(defgeneric insert-address (object item start-address &optional end-address)\n (:documentation\n \"Insert ITEM into OBJECT between START-ADDRESS and END-ADDRESS.\"))\n\n(defgeneric delete-address (object item start-address &optional end-address)\n (:documentation\n \"Delete ITEM from OBJECT between START-ADDRESS and END-ADDRESS.\"))\n\n(defgeneric at-address (object address)\n (:documentation\n \"Find all objects in OBJECT starting at ADDRESS.\"))\n\n(defgeneric on-address (object start-address &optional end-address)\n (:documentation\n \"Find all objects in OBJECT between START-ADDRESS and END-ADDRESS.\"))\n\n(defgeneric set-parent-uuid (new uuid object)\n (:documentation \"Set UUID to NEW in OBJECT's parent.\"))\n\n(defgeneric update-proto (proto-backed-object)\n (:documentation\n \"Update and return the `proto' field of PROTO-BACKED-OBJECT.\nThis will ensure that any changes made to PROTO-BACKED-OBJECT outside\nof its protocol buffer, e.g. any slots initialized using the\n:from-proto option to `define-proto-backed-class', are synchronized\nagainst the object's protocol buffer.\")\n (:method ((proto-backed-object proto-backed))\n (proto proto-backed-object)))\n\n(defgeneric address-range (proto-backed-object)\n (:documentation\n \"Return any address range of the PROTO-BACKED-OBJECT GTIRB object.\"))\n\n(defmacro define-proto-backed-class ((class proto-class) super-classes\n slot-specifiers proto-fields\n &rest options)\n \"Define a Common Lisp class backed by a protobuf class.\nSLOT-SPECIFIERS is as in `defclass' with the addition of optional\n:to-proto and :from-proto fields, which may take protobuf\nserialization functions, and :skip-equal-p field which causes\n`is-equal-p' to skip that field. PROTO-FIELDS may hold a list of\nfields which pass through directly to the backing protobuf class. The\n:parent option names the field holding the containing protobuf\nelement. The :address-range option holds the logic to calculate an\naddress range for instances of the object.\"\n (nest\n (flet ((plist-get (item list)\n (second (member item list)))\n (plist-drop (item list)\n (if-let ((location (position item list)))\n (append (subseq list 0 location)\n (subseq list (+ 2 location)))\n list))))\n (let ((from-proto-slots (remove-if-not {find :from-proto} slot-specifiers))\n (to-proto-slots (remove-if-not {find :to-proto} slot-specifiers))\n (parent (second (assoc :parent options)))\n (address-range (cdr (assoc :address-range options)))))\n `(progn\n (defclass ,class (proto-backed ,@super-classes)\n ;; Accessors for normal lisp classes\n ((proto :initarg :proto :accessor proto :type ,proto-class\n :initform ,(if parent\n `(let ((it (make-instance ',proto-class)))\n (setf (proto::uuid it) (new-uuid))\n it)\n `(make-instance ',proto-class))\n :documentation \"Backing protobuf object.\nShould not need to be manipulated by client code.\")\n (ir :accessor ir :type (or null gtirb)\n :initarg :ir\n :initform nil\n :documentation\n ,(format nil \"Access the top-level IR of this ~a.\" class))\n ;; TODO: Consider throwing warnings in a `setf :around'\n ;; defmethod on the parents of objects with parents if\n ;; the objects are set to something that already has a\n ;; current parent. This could avoid surprising\n ;; inconsistencies. Alternately this could throw an\n ;; error with the option to copy the object with a new\n ;; corrected parent or to set the parent directly.\n ,@(when parent\n `((,parent :accessor ,parent :type (or null ,parent)\n :initarg ,(make-keyword parent)\n :initform nil\n :documentation ,(format nil \"Access the ~a of this ~a.\"\n parent class))))\n ,@(mapcar [{plist-drop :to-proto} {plist-drop :from-proto}\n {plist-drop :proto-field} {plist-drop :skip-equal-p}]\n slot-specifiers))\n ,@(remove-if [«or {eql :parent} {eql :address-range}» #'car] options))\n ,@(when parent\n `((defmethod get-uuid (uuid (object ,class))\n (assert (or (ir object) (,parent object)) (object)\n ,(format nil\n \"`get-uuid' failed on a ~a without a ~a\"\n class parent))\n (get-uuid uuid (or (ir object) (,parent object))))\n (defmethod set-parent-uuid (new uuid (object ,class))\n (assert (or (ir object) (,parent object)) (object)\n ,(format nil\n \"`set-parent-uuid' failed on a ~a without a ~a\"\n class parent))\n (setf (get-uuid uuid (or (ir object) (,parent object))) new))\n (defmethod (setf get-uuid) (new uuid (object ,class))\n (assert (or (ir object) (,parent object)) (object)\n ,(format nil\n \"`get-uuid' failed on ~a without a ~a\"\n class parent))\n (set-parent-uuid new uuid object))\n (defmethod remove-uuid (uuid (object ,class))\n (assert (or (ir object) (,parent object)) (object)\n ,(format nil\n \"`remove-uuid' failed on ~a without a ~a\"\n class parent))\n (remove-uuid uuid (or (ir object) (,parent object))))\n (defmethod at-address ((object ,class) address)\n (assert (or (ir object) (,parent object)) (object)\n ,(format nil\n \"`at-address' failed on ~a without a ~a\"\n class parent))\n (at-address (or (ir object) (,parent object)) address))\n (defmethod on-address ((object ,class) start &optional end)\n (assert (or (ir object) (,parent object)) (object)\n ,(format nil\n \"`on-address' failed on ~a without a ~a\"\n class parent))\n (on-address (or (ir object) (,parent object)) start end))))\n (defmethod address-range ((self ,class)) ,@address-range)\n (defmethod\n initialize-instance :after ((self ,class) &key)\n ,@(when parent\n `((when (,parent self)\n (setf (get-uuid (uuid-to-integer (proto:uuid (proto self)))\n self)\n self))))\n (with-slots (proto ,@(mapcar #'car from-proto-slots)) self\n ,@(mapcar\n (lambda (spec)\n (destructuring-bind\n (slot &key from-proto &allow-other-keys) spec\n `(setf ,slot (funcall ,from-proto proto))))\n from-proto-slots)))\n (defmethod update-proto ((self ,class))\n ,@(mapcar\n (lambda (spec)\n (destructuring-bind\n (slot &key to-proto (proto-field slot) &allow-other-keys)\n spec\n `(setf (,(intern (symbol-name proto-field) 'proto) (proto self))\n (funcall ,to-proto (,slot self)))))\n to-proto-slots)\n (proto self))\n ;; Equality check on class.\n ;;\n ;; NOTE: For this to work we might need to add an optional :only\n ;; field to both slot-specifiers and proto-fields. This\n ;; would mean that the equality of this field is only\n ;; checked with this form returns true. E.g., on\n ;; byte-intervals we could say:\n ;; (address :type unsigned-byte-64 :only #'addressp)\n (defmethod is-equal-p-internal ((left ,class) (right ,class))\n (and ,@(mapcar\n (lambda (accessor)\n `(compare-or-verbose is-equal-p-internal\n (,accessor left) (,accessor right)))\n (append\n (mapcar {plist-get :accessor}\n (remove-if {plist-get :skip-equal-p}\n slot-specifiers))\n (mapcar #'car proto-fields)))))\n ;; Pass-through accessors for protobuf fields so they operate\n ;; directly on the backing protobuf object.\n ,@(apply\n #'append\n (mapcar\n (nest\n (lambda (pair))\n (destructuring-bind\n (name &key type documentation enumeration (proto-field name)\n &allow-other-keys) pair)\n (let ((base `(,(intern (symbol-name proto-field) 'proto)\n (proto obj)))))\n `((defmethod ,name ((obj ,class))\n ,@(when documentation (list documentation))\n ,(ecase type\n ((unsigned-byte-64 boolean bytes) base)\n (enumeration `(cdr (assoc ,base ,enumeration)))\n (uuid `(uuid-to-integer ,base))\n (string `(pb:string-value ,base))))\n (defmethod (setf ,name) (new (obj ,class))\n ,@(when documentation (list documentation))\n ,(ecase type\n ((unsigned-byte-64 boolean) `(setf ,base new))\n (bytes `(setf ,base (force-byte-array new)))\n (enumeration `(setf ,base (car (rassoc new ,enumeration))))\n (uuid `(setf ,base (integer-to-uuid new)))\n (string `(setf ,base (pb:string-field new)))))))\n proto-fields)))))\n\n(eval-when (:compile-toplevel :load-toplevel :execute)\n (defvar aux-data-slot-definition\n \"A-list of auxiliary data objects keyed by string name.\nAux-Data tables may hold structured or unstructured data. This data\nmay refer to elements of the GTIRB IR through uuids. Information\nrelevant to a particular module will be stored in Aux-Data tables\naccessible from the specific module. Aux-Data tables only exist on\nmodules and on GTIRB IR instances.\"))\n\n\f\n;;;; Classes.\n(define-proto-backed-class (gtirb proto:ir) ()\n ((modules :initarg modules :accessor modules :type list\n :initform nil\n :from-proto\n [{mapcar {make-instance 'module :ir self :gtirb self :proto}}\n {coerce _ 'list} #'proto:modules]\n :to-proto {map 'vector #'update-proto}\n :documentation\n \"List of the modules on a top-level GTIRB IR instance.\")\n (cfg :accessor cfg :type digraph\n :from-proto\n (lambda (proto)\n (let ((p-cfg (proto:cfg proto)))\n (populate\n (make-instance 'digraph)\n :edges-w-values\n (mapcar\n (lambda (edge)\n (cons (list (uuid-to-integer (proto:source-uuid edge))\n (uuid-to-integer (proto:target-uuid edge)))\n (make-instance 'edge-label :proto (proto:label edge))))\n (coerce (proto:edges p-cfg) 'list))\n :nodes (map 'list #'uuid-to-integer (proto:vertices p-cfg)))))\n :to-proto\n (lambda (cfg &aux (p-cfg (make-instance 'proto:cfg)))\n (setf\n (proto:vertices p-cfg)\n (map 'vector #'integer-to-uuid (nodes cfg))\n (proto:edges p-cfg)\n (map 'vector\n (lambda (edge)\n (destructuring-bind ((source target) . label) edge\n (let ((p-edge (make-instance 'proto:edge)))\n (setf\n (proto:source-uuid p-edge) (integer-to-uuid source)\n (proto:target-uuid p-edge) (integer-to-uuid target)\n (proto:label p-edge) (proto label))\n p-edge)))\n (edges-w-values cfg)))\n p-cfg)\n :documentation\n \"Control flow graph (CFG) represented as a `graph:digraph'.\nNodes in the graph hold the UUIDs of code blocks which may be looked\nup using `get-uuid'. Edges on the graph are labeled with `edge-label'\nobjects which provide information on the nature of the control flow of\nthe graph.\")\n (aux-data :accessor aux-data :type list\n :from-proto #'aux-data-from-proto\n :to-proto #'aux-data-to-proto\n :documentation #.aux-data-slot-definition)\n (by-uuid :accessor by-uuid :initform (make-hash-table) :type hash-table\n :skip-equal-p t\n :documentation \"Internal cache for UUID-based lookup.\")\n (by-address :accessor by-address :initform (make-ranged) :skip-equal-p t\n :documentation \"Internal cache for Address-based lookup.\")\n (aux-data-w-offsets :accessor aux-data-w-offsets :initform nil\n :skip-equal-p t\n :documentation \"Cache for fast offset updates.\"))\n ((version :type unsigned-byte-64 :documentation \"Protobuf version.\"))\n (:documentation \"Base class of an instance of GTIRB IR.\"))\n\n(defmethod initialize-instance :around ((self gtirb) &key)\n (call-next-method)\n ;; Populate the aux-data tables with offsets.\n (setf (aux-data-w-offsets self) (get-aux-data-w-offsets self)))\n\n(define-condition ir (error)\n ((message :initarg :message :initform nil :reader message)\n (object :initarg :object :initform nil :reader object))\n (:report (lambda (condition stream)\n (format stream \"GTIRB error ~S on ~S.\"\n (message condition) (object condition))))\n (:documentation \"Condition raised on GTIRB data structure violations.\"))\n\n(defmethod print-object ((obj gtirb) stream)\n (print-unreadable-object (obj stream :type t :identity t)\n (format stream \"~a\" (modules obj))))\n\n(defmethod ir ((obj gtirb)) obj)\n\n(defmethod get-uuid (uuid (obj gtirb))\n (gethash uuid (by-uuid obj)))\n\n(defmethod (setf get-uuid) (new uuid (obj gtirb))\n (when (zerop uuid)\n (warn \"Saving object ~a without a UUID into ~a.\" new obj))\n (when-let ((range (address-range new)))\n #+debug (format t \"(range ~S) ;; => ~S~%\" new range)\n (apply #'insert-address obj new range))\n (setf (gethash uuid (by-uuid obj)) new))\n\n(defmethod remove-uuid (uuid (obj gtirb))\n (remhash uuid (by-uuid obj)))\n\n(defmethod insert-address ((gtirb gtirb) item start &optional end)\n (ranged-insert (by-address gtirb) (uuid item) start end))\n\n(defmethod delete-address ((gtirb gtirb) item start &optional end)\n (ranged-delete (by-address gtirb) (uuid item) start end))\n\n(defmethod at-address ((gtirb gtirb) address)\n (mapcar {get-uuid _ gtirb} (ranged-find-at (by-address gtirb) address)))\n\n(defmethod on-address ((gtirb gtirb) start &optional (end start))\n (mapcar {get-uuid _ gtirb} (ranged-find (by-address gtirb) start end)))\n\n(define-constant +module-isa-map+\n '((#.proto:+isa-isa-undefined+ . :undefined)\n (#.proto:+isa-ia32+ . :ia32)\n (#.proto:+isa-ppc32+ . :ppc32)\n (#.proto:+isa-x64+ . :x64)\n (#.proto:+isa-arm+ . :arm)\n (#.proto:+isa-valid-but-unsupported+ . :valid-but-unsupported)\n (#.proto:+isa-ppc64+ . :ppc64)\n (#.proto:+isa-arm64+ . :arm64)\n (#.proto:+isa-mips32+ . :mips32)\n (#.proto:+isa-mips64+ . :mips64))\n :test #'equal)\n\n(define-constant +module-file-format-map+\n '((#.proto:+file-format-coff+ . :coff)\n (#.proto:+file-format-elf+ . :elf)\n (#.proto:+file-format-ida-pro-db32+ . :ida-pro-db32)\n (#.proto:+file-format-ida-pro-db64+ . :ida-pro-db64)\n (#.proto:+file-format-macho+ . :macho)\n (#.proto:+file-format-pe+ . :pe)\n (#.proto:+file-format-raw+ . :raw)\n (#.proto:+file-format-xcoff+ . :xcoff)\n (#.proto:+file-format-format-undefined+ . :format-undefined))\n :test #'equal)\n\n(define-constant +module-byte-order-map+\n `((#.proto:+byte-order-byte-order-undefined+ . :undefined)\n (#.proto:+byte-order-big-endian+ . :big-endian)\n (#.proto:+byte-order-little-endian+ . :little-endian))\n :test #'equal)\n\n(define-proto-backed-class (module proto:module) ()\n ((proxies :accessor proxies :type hash-table\n :initform (make-hash-table)\n :from-proto\n (lambda (proto &aux (table (make-hash-table)))\n (let ((proto-proxies (proto:proxies proto)))\n (dotimes (n (length proto-proxies) table)\n (let ((it (aref proto-proxies n)))\n (setf (gethash (uuid-to-integer (proto:uuid it)) table)\n (make-instance 'proxy-block\n :ir (ir self) :module self :proto it))))))\n :to-proto\n [{map 'vector (lambda (uuid)\n (let ((it (make-instance 'proto:proxy-block)))\n (setf (proto:uuid it) (integer-to-uuid uuid))\n it))}\n {mapcar #'car} #'hash-table-alist]\n :documentation\n \"Hash-table of proxy-blocks keyed by UUID.\nProxy-blocks in GTIRB are used to represent cross-module linkages.\nFor example when code in a module calls to a function defined in an\nexternal library, the CFG for that IR instance may represent this call\nwith a call edge to a proxy block representing the external called\nfunction.\")\n (symbols :accessor symbols :type list\n :initform nil\n :from-proto\n [{map 'list\n {make-instance 'symbol :ir (ir self) :module self :proto}}\n #'proto:symbols]\n :to-proto {map 'vector #'update-proto}\n :documentation \"Hash-table of symbols keyed by UUID.\")\n (sections :accessor sections :type list\n :from-proto\n [{map 'list\n {make-instance 'section :ir (ir self) :module self :proto}}\n #'proto:sections]\n :to-proto {map 'vector #'update-proto}\n :documentation \"List of the sections comprising this module.\")\n (aux-data :accessor aux-data :type list\n :from-proto #'aux-data-from-proto\n :to-proto #'aux-data-to-proto\n :documentation #.aux-data-slot-definition))\n ((name :type string :documentation\n \"An optional human-readable name for this module.\")\n (binary-path :type string :documentation\n \"The path or filename for this module.\nE.g, the name of a dynamically loaded library or of the main\nexecutable.\")\n (preferred-addr :type unsigned-byte-64 :documentation\n \"Some systems specify a preferred address in memory.\nOn those systems this field may be used to capture this address.\")\n (rebase-delta :type unsigned-byte-64 :documentation\n \"The difference between this module's and\n`preferred-addr' and the address at which it was actually loaded.\")\n (isa :type enumeration :enumeration +module-isa-map+ :documentation\n \"The instruction set architecture (ISA) of the code in this module.\")\n (file-format :type enumeration :enumeration +module-file-format-map+\n :documentation\n \"The binary file format of the original file this\nmodule represents.\")\n (byte-order :type enumeration :enumeration +module-byte-order-map+ :documentation\n \"The byte-order of the bytes in this module.\"))\n (:documentation \"Module of a GTIRB IR instance.\") (:parent gtirb))\n\n(defmethod make-instance :around\n ((class (eql 'module)) &rest initargs &key &allow-other-keys)\n (let ((proto (or (getf initargs :proto)\n (let ((new-proto (make-instance 'proto:module)))\n (if-let ((name (getf initargs :name)))\n (setf (proto:name new-proto) (pb:string-field name))\n (warn \"Modules created without a name\"))\n new-proto))))\n (apply #'call-next-method class :proto proto initargs)))\n\n(defmethod print-object ((obj module) stream)\n (print-unreadable-object (obj stream :type t :identity t)\n (format stream \"~a ~a ~s\" (file-format obj) (isa obj) (name obj))))\n\n(defgeneric get-aux-data-w-offsets (object)\n (:documentation \"Collect all Aux-Data tables with offsets in their types.\")\n (:method ((list list))\n (remove-if-not [{find :offset} #'flatten #'aux-data-type #'cdr] list))\n (:method ((self module)) (get-aux-data-w-offsets (aux-data self)))\n (:method ((self gtirb))\n (apply #'append\n (get-aux-data-w-offsets (aux-data self))\n (mapcar #'get-aux-data-w-offsets (modules self)))))\n\n(defmethod (setf aux-data) :after (new-value (self gtirb))\n (declare (ignorable new-value))\n (setf (aux-data-w-offsets self) (get-aux-data-w-offsets self)))\n\n(defmethod (setf aux-data) :after (new-value (self module))\n (declare (ignorable new-value))\n (setf (aux-data-w-offsets (ir self)) (get-aux-data-w-offsets (ir self))))\n\n(define-constant +edge-label-type-map+\n '((#.proto:+edge-type-type-branch+ . :branch)\n (#.proto:+edge-type-type-call+ . :call)\n (#.proto:+edge-type-type-fallthrough+ . :fallthrough)\n (#.proto:+edge-type-type-return+ . :return)\n (#.proto:+edge-type-type-syscall+ . :syscall)\n (#.proto:+edge-type-type-sysret+ . :sysret))\n :test #'equal)\n\n(define-proto-backed-class (edge-label proto:edge-label) () ()\n ((conditional :type boolean :documentation\n \"This is true if this edge is due to a conditional\ninstruction.\")\n (direct :type boolean :documentation\n \"Is this a direct (as opposed to indirect) control flow edge.\")\n (edge-type :type enumeration :enumeration +edge-label-type-map+\n :proto-field type :documentation\n \"The type of an edge indicates the nature of the\ncontrol flow along it. E.g., \\\"branch,\\\" \\\"call,\\\" \\\"fallthrough,\\\"\nand \\\"return\\\" are examples.\"))\n (:documentation \"Label on a CFG edge.\nThis indicates the type of control flow along this edge.\"))\n\n(defmethod print-object ((obj edge-label) stream)\n (print-unreadable-object (obj stream :type t :identity t)\n (format stream \"~a ~:[unconditional~;conditional~] ~:[undirect~;direct~]\"\n (edge-type obj) (conditional obj) (direct obj))))\n\n(define-proto-backed-class (symbol proto:symbol) () ()\n ((name :type string)\n (value :type unsigned-byte-64)\n (referent-uuid :type uuid)\n (at-end :type boolean))\n (:documentation\n \"Symbol with it's NAME and an optional VALUE or REFERENT.\")\n (:parent module))\n\n(defgeneric payload (symbol)\n (:documentation \"Provide access to the referent or value of SYMBOL.\")\n (:method ((symbol symbol))\n (cond\n ((proto:has-value (proto symbol))\n (value symbol))\n ((proto:has-referent-uuid (proto symbol))\n (get-uuid (referent-uuid symbol) symbol)))))\n\n(defmethod (setf payload) ((new proto-backed) (symbol symbol))\n \"Save GTIRB object NEW into the `referent-uuid' of SYMBOL.\"\n (proto:clear-value (proto symbol))\n (setf (referent-uuid symbol) (uuid new)))\n\n(defmethod (setf payload) ((new integer) (symbol symbol))\n \"Save INTEGER value NEW into the `value' of SYMBOL.\"\n (proto:clear-referent-uuid (proto symbol))\n (setf (value symbol) new))\n\n(defmethod (setf payload) ((new t) (symbol symbol))\n (error \"Symbol payload ~S must be either a GTIRB element or an integer.\" new))\n\n(defmethod print-object ((obj symbol) stream)\n (print-unreadable-object (obj stream :type t :identity t)\n (format stream \"~a ~a~:[~;|~]\" (name obj)\n (or (value obj) (referent-uuid obj))\n (at-end obj))))\n\n(define-constant +section-flags-map+\n '((#.proto:+section-flag-section-undefined+ . :flag-undefined)\n (#.proto:+section-flag-readable+ . :readable)\n (#.proto:+section-flag-writable+ . :writable)\n (#.proto:+section-flag-executable+ . :executable)\n (#.proto:+section-flag-loaded+ . :loaded)\n (#.proto:+section-flag-initialized+ . :initialized)\n (#.proto:+section-flag-thread-local+ . :thread-local))\n :test #'equal)\n\n(define-proto-backed-class (section proto:section) ()\n ((byte-intervals\n :accessor byte-intervals :type list\n :from-proto\n [{map 'list\n {make-instance 'byte-interval :ir (ir self) :section self :proto}}\n #'proto:byte-intervals]\n :to-proto {map 'vector #'update-proto}\n :documentation \"Byte-intervals holding all of the section's bytes.\"))\n ((name :type string :documentation \"Name of this section.\")\n (flags :type enumeration :enumeration +section-flags-map+\n :proto-field section-flags :documentation\n \"Flags holding common properties of this section.\nThese flags only hold those section properties which are relatively\nuniversal including read, write, execute permissions, whether the\nsection is loaded into memory at run-time or not, whether the section\nis zero initialized, and whether the section is thread-local.\"))\n (:documentation \"Section in a GTIRB IR instance.\") (:parent module))\n\n(defmethod print-object ((obj section) stream)\n (print-unreadable-object (obj stream :type t :identity t)\n (format stream \"~a ~a\" (name obj) (length (byte-intervals obj)))))\n\n(defmethod address ((obj section))\n (extremum (mapcar #'address (byte-intervals obj)) #'<))\n\n(defmethod size ((it section))\n (- (extremum (mapcar «+ #'address #'size» (byte-intervals it)) #'> :key #'car)\n (address it)))\n\n(defgeneric blocks (obj)\n (:documentation \"List of gtirb-byte-block objects in this object.\nPrimitive accessor for byte-interval.\")\n (:method ((obj gtirb)) (mappend #'blocks (modules obj)))\n (:method ((obj module)) (mappend #'blocks (sections obj)))\n (:method ((obj section)) (mappend #'blocks (byte-intervals obj))))\n\n(define-proto-backed-class (offset proto:offset) () ()\n ((element-id :type uuid)\n (displacement :type unsigned-byte-64))\n (:documentation \"Offset into a GTIRB object.\"))\n\n(define-constant +se-attribute-flag-map+\n '(\n (#.proto:+se-attribute-flag-got+ . :got)\n (#.proto:+se-attribute-flag-gotpc+ . :gotpc)\n (#.proto:+se-attribute-flag-gotoff+ . :gotoff)\n (#.proto:+se-attribute-flag-gotrel+ . :gotrel)\n (#.proto:+se-attribute-flag-plt+ . :plt)\n (#.proto:+se-attribute-flag-pltoff+ . :pltoff)\n (#.proto:+se-attribute-flag-pcrel+ . :pcrel)\n (#.proto:+se-attribute-flag-secrel+ . :secrel)\n (#.proto:+se-attribute-flag-tls+ . :tls)\n (#.proto:+se-attribute-flag-tlsgd+ . :tlsgd)\n (#.proto:+se-attribute-flag-tlsld+ . :tlsld)\n (#.proto:+se-attribute-flag-tlsldm+ . :tlsldm)\n (#.proto:+se-attribute-flag-tlscall+ . :tlscall)\n (#.proto:+se-attribute-flag-tlsdesc+ . :tlsdesc)\n (#.proto:+se-attribute-flag-tprel+ . :tprel)\n (#.proto:+se-attribute-flag-tpoff+ . :tpoff)\n (#.proto:+se-attribute-flag-dtprel+ . :dtprel)\n (#.proto:+se-attribute-flag-dtpoff+ . :dtpoff)\n (#.proto:+se-attribute-flag-dtpmod+ . :dtpmod)\n (#.proto:+se-attribute-flag-ntpoff+ . :ntpoff)\n (#.proto:+se-attribute-flag-page+ . :page)\n (#.proto:+se-attribute-flag-pageoff+ . :pageoff)\n (#.proto:+se-attribute-flag-call+ . :call)\n (#.proto:+se-attribute-flag-lo+ . :lo)\n (#.proto:+se-attribute-flag-hi+ . :hi)\n (#.proto:+se-attribute-flag-higher+ . :higher)\n (#.proto:+se-attribute-flag-highest+ . :highest)\n (#.proto:+se-attribute-flag-gotntpoff+ . :gotntpoff)\n (#.proto:+se-attribute-flag-indntpoff+ . :indntpoff)\n (#.proto:+se-attribute-flag-g0+ . :g0)\n (#.proto:+se-attribute-flag-g1+ . :g1)\n (#.proto:+se-attribute-flag-g2+ . :g2)\n (#.proto:+se-attribute-flag-g3+ . :g3)\n (#.proto:+se-attribute-flag-upper16+ . :upper16)\n (#.proto:+se-attribute-flag-lower16+ . :lower16)\n (#.proto:+se-attribute-flag-lo12+ . :lo12)\n (#.proto:+se-attribute-flag-lo15+ . :lo15)\n (#.proto:+se-attribute-flag-lo14+ . :lo14)\n (#.proto:+se-attribute-flag-hi12+ . :hi12)\n (#.proto:+se-attribute-flag-hi21+ . :hi21)\n (#.proto:+se-attribute-flag-s+ . :s)\n (#.proto:+se-attribute-flag-pg+ . :pg)\n (#.proto:+se-attribute-flag-nc+ . :nc)\n (#.proto:+se-attribute-flag-abs+ . :abs)\n (#.proto:+se-attribute-flag-prel+ . :prel)\n (#.proto:+se-attribute-flag-prel31+ . :prel31)\n (#.proto:+se-attribute-flag-target1+ . :target1)\n (#.proto:+se-attribute-flag-target2+ . :target2)\n (#.proto:+se-attribute-flag-sbrel+ . :sbrel)\n (#.proto:+se-attribute-flag-tlsldo+ . :tlsldo)\n (#.proto:+se-attribute-flag-hi16+ . :hi16)\n (#.proto:+se-attribute-flag-lo16+ . :lo16)\n (#.proto:+se-attribute-flag-gprel+ . :gprel)\n (#.proto:+se-attribute-flag-disp+ . :disp)\n (#.proto:+se-attribute-flag-ofst+ . :ofst)\n (#.proto:+se-attribute-flag-h+ . :h)\n (#.proto:+se-attribute-flag-l+ . :l)\n (#.proto:+se-attribute-flag-ha+ . :ha)\n (#.proto:+se-attribute-flag-high+ . :high)\n (#.proto:+se-attribute-flag-higha+ . :higha)\n (#.proto:+se-attribute-flag-highera+ . :highera)\n (#.proto:+se-attribute-flag-highesta+ . :highesta)\n (#.proto:+se-attribute-flag-tocbase+ . :tocbase)\n (#.proto:+se-attribute-flag-toc+ . :toc)\n (#.proto:+se-attribute-flag-notoc+ . :notoc))\n :test #'equal\n :documentation \"See doc/general/SymbolicExpression.md for more details.\")\n\n(define-proto-backed-class (byte-interval proto:byte-interval) ()\n ((blocks :initarg :blocks :accessor blocks :type list\n :from-proto\n [{map 'list\n (lambda (proto-block)\n (let ((it (cond\n ((not (emptyp\n (proto:uuid (proto:data proto-block))))\n (make-instance 'data-block\n :ir (ir self)\n :byte-interval self\n :offset (proto:offset proto-block)\n :proto (proto:data proto-block)))\n ((not (emptyp\n (proto:uuid (proto:code proto-block))))\n (make-instance 'code-block\n :ir (ir self)\n :byte-interval self\n :offset (proto:offset proto-block)\n :proto (proto:code proto-block))))))\n #+debug\n (when (emptyp (proto:uuid (proto it)))\n (warn \"BAD BLOCK ~a with empty uuid from ~a.~%~A~%\"\n it (name (section self)) proto-block))\n it))}\n #'proto:blocks]\n :to-proto\n {map 'vector\n (lambda (gtirb-block)\n (let ((it (make-instance 'proto:block)))\n (setf (proto:offset it) (offset gtirb-block))\n (etypecase gtirb-block\n (code-block\n (setf (proto:code it) (update-proto gtirb-block)))\n (data-block\n (setf (proto:data it) (update-proto gtirb-block))))\n it))}\n :documentation\n \"Blocks in this byte-interval.\nThis list could include `code-block' or `data-block' elements (which\nboth subclass the `gtirb-byte-block' class) but not `proxy-block'\nelements as proxy blocks do not hold bytes.\")\n (symbolic-expressions\n :accessor symbolic-expressions :type hash-table\n :initarg :symbolic-expressions\n :from-proto\n (lambda (proto &aux (table (make-hash-table)))\n (flet ((process-symbols (&rest symbols)\n (mappend (lambda (uuid)\n (if-let ((sym (get-uuid (uuid-to-integer uuid)\n (ir self))))\n (list sym)\n (unless (emptyp uuid)\n (warn \"Symbol UUID ~S not found\" uuid))))\n symbols)))\n (dotimes (n (length (proto:symbolic-expressions proto)) table)\n (let* ((proto (aref (proto:symbolic-expressions proto) n))\n (offset (proto:key proto))\n (attribute-flags\n (map 'list [#'cdr {assoc _ +se-attribute-flag-map+}]\n (proto:attribute-flags (proto:value proto))))\n (symbolic-expression (proto:value proto)))\n (setf (gethash offset table)\n (cond\n ((proto:has-addr-const symbolic-expression)\n (make-instance 'sym-addr-const\n :ir (ir self)\n :attribute-flags attribute-flags\n :symbols (process-symbols\n (proto:symbol-uuid\n (proto:addr-const symbolic-expression)))\n :proto (proto:addr-const symbolic-expression)))\n ((proto:has-addr-addr symbolic-expression)\n (make-instance 'sym-addr-addr\n :ir (ir self)\n :attribute-flags attribute-flags\n :symbols (process-symbols\n (proto:symbol1-uuid\n (proto:addr-addr symbolic-expression))\n (proto:symbol2-uuid\n (proto:addr-addr symbolic-expression)))\n :proto (proto:addr-addr symbolic-expression)))\n (t (assert \"Symbolic expression of unknown kind.\"))))))))\n :to-proto\n [{map 'vector\n (lambda (pair)\n (destructuring-bind (offset . symbolic-expression) pair\n (flet ((force-attribute-flags-array (array)\n (declare (type (simple-array) array))\n (make-array (length array)\n :element-type `(mod ,(length +se-attribute-flag-map+))\n :initial-contents array)))\n (let ((it (make-instance\n 'proto:byte-interval-symbolic-expressions-entry)))\n (setf (proto:key it) offset\n (proto:value it)\n (let ((it (make-instance 'proto:symbolic-expression)))\n (when (attribute-flags symbolic-expression)\n (setf (proto:attribute-flags it)\n (force-attribute-flags-array\n (map 'vector\n [#'car {rassoc _ +se-attribute-flag-map+}]\n (attribute-flags symbolic-expression)))))\n (etypecase symbolic-expression\n (sym-addr-const\n (setf (proto:addr-const it)\n (update-proto symbolic-expression)))\n (sym-addr-addr\n (setf (proto:addr-addr it)\n (update-proto symbolic-expression))))\n it))\n it))))}\n #'hash-table-alist]\n :documentation \"Hash of symbolic-expressions keyed by offset.\"))\n ((addressp :type boolean :proto-field has-address\n :documentation\n \"Does this byte-interval have an address.\")\n (address :type unsigned-byte-64\n :documentation\n \"Optionally specify the address in memory at which this\n~ byte-interval should start. Byte-intervals without address could\nexist anywhere in memory.\")\n (size :type unsigned-byte-64 :documentation\n \"The size of this byte-interval.\nIt is possible for the size of a byte-interval to be larger than the\nnumber of bytes in the byte interval's `contents' if portions of the\nbyte-interval are not represented statically but are zero-initialized\nat runtime.\")\n (contents :type bytes :documentation\n \"A vector holding the actual bytes of this byte interval.\"))\n (:documentation \"Byte-interval in a GTIRB instance.\") (:parent section)\n (:address-range (when (addressp self)\n (list (address self) (+ (address self) (size self))))))\n\n(defmethod (setf size) :before (new (obj byte-interval))\n (restart-case\n (when (> (length (contents obj)) new)\n (error (make-condition 'ir\n :message \"size smaller than contents\"\n :object obj)))\n (truncate-contents ()\n :report \"Truncate the contents of the byte-interval to the new size.\"\n (setf (contents obj) (subseq (contents obj) 0 new)))\n (ignore ()\n :report \"Ignore and leave the byte-interval in an inconsistent state.\")))\n\n(defmethod print-object ((obj byte-interval) stream)\n (print-unreadable-object (obj stream :type t :identity t)\n (format stream \"~a ~a\"\n (if (addressp obj) (address obj) \"?\")\n (size obj))))\n\n(defmethod address ((obj byte-interval))\n (when (addressp obj) (proto:address (proto obj))))\n\n(defclass symbolic-expression ()\n ((symbols :accessor symbols :initarg :symbols :initform nil :type list\n :documentation \"Symbol(s) appearing in this symbolic expression.\")\n (attribute-flags :accessor attribute-flags :initarg :attribute-flags\n :initform nil :type list\n :documentation \"Attributes holding the relocation type.\")))\n\n(defmethod print-object ((obj symbolic-expression) stream)\n (print-unreadable-object (obj stream :type t :identity t)\n (format stream \"~a ~{~a~^, ~}\" (offset obj) (symbols obj))))\n\n;;; TODO: If we get symbolic expressions for these, then add the\n;;; following to each `symbolic-expression' class:\n;;;\n;;; (:parent byte-interval)\n;;; (:address-range (when-let ((range (addressp (byte-interval self))))\n;;; (+ (offset self) (first range))))\n;;;\n;;; and then go back up and add \":byte-interval self\" to their\n;;; `make-instance' calls in byte-interval.\n(define-proto-backed-class\n (sym-addr-const proto:sym-addr-const) (symbolic-expression) ()\n ((offset :type unsigned-byte-64))\n (:address-range (when (addressp (byte-interval self))\n (let ((address (+ (address (byte-interval self))\n (offset self))))\n (list address address)))))\n\n(define-proto-backed-class\n (sym-addr-addr proto:sym-addr-addr) (symbolic-expression) ()\n ((offset :type unsigned-byte-64)\n (scale :type unsigned-byte-64))\n (:address-range (when (addressp (byte-interval self))\n (let ((address (+ (address (byte-interval self))\n (offset self))))\n (list address address)))))\n\n(defmethod update-proto :before ((sym sym-addr-const))\n (setf (proto:symbol-uuid (proto sym))\n (integer-to-uuid (uuid (first (symbols sym))))))\n\n(defmethod update-proto :before ((sym sym-addr-addr))\n (setf (proto:symbol1-uuid (proto sym))\n (integer-to-uuid (uuid (first (symbols sym))))\n (proto:symbol2-uuid (proto sym))\n (integer-to-uuid (uuid (second (symbols sym))))))\n\n(defmethod update-proto :before ((sym sym-addr-const))\n (setf (proto:symbol-uuid (proto sym))\n (integer-to-uuid (uuid (first (symbols sym))))))\n\n(defmethod update-proto :before ((sym sym-addr-addr))\n (setf (proto:symbol1-uuid (proto sym))\n (integer-to-uuid (uuid (first (symbols sym))))\n (proto:symbol2-uuid (proto sym))\n (integer-to-uuid (uuid (second (symbols sym))))))\n\n(defclass gtirb-block () ())\n\n(defclass gtirb-byte-block (gtirb-block) ()\n (:documentation \"Super-class of the `code-block' and `data-block' classes.\nThis class abstracts over all GTIRB blocks which are able to hold bytes.\"))\n\n(defmethod symbolic-expressions ((bb gtirb-byte-block))\n (nest\n (alist-hash-table)\n (remove-if-not [«and {< (offset bb)} {>= (+ (offset bb) (size bb))}» #'car])\n (hash-table-alist)\n (symbolic-expressions)\n (byte-interval bb)))\n\n(defmethod address ((obj gtirb-byte-block))\n (when-let ((base-address (address (byte-interval obj))))\n (+ base-address (offset obj))))\n\n(defgeneric bytes (object &optional start end)\n (:documentation \"Return the bytes held by OBJECT.\")\n (:method ((obj byte-interval) &optional (start 0) end)\n (if end\n (subseq (contents obj) start end)\n (subseq (contents obj) start)))\n (:method ((obj gtirb-byte-block) &optional (start 0) (end (size obj)))\n #+debug (format t \"[~S] ~S:[~S:~S]<-[~S:~S]~%\"\n (proto:uuid (proto obj))\n (name (section (byte-interval obj)))\n (or (and (addressp (byte-interval obj))\n (address (byte-interval obj)))\n \"?\")\n (size (byte-interval obj))\n (offset obj) (size obj))\n (let* ((start (+ (offset obj) start))\n (end (+ (offset obj) end)))\n (assert (<= end (size (byte-interval obj))) (obj)\n \"Block's end ~d exceeds size of containing byte-interval ~d.\"\n end (size (byte-interval obj)))\n (let ((real-end (length (contents (byte-interval obj)))))\n (cond\n ((<= end real-end) ; Allocated bytes.\n (subseq (contents (byte-interval obj)) start end))\n ((<= start real-end) ; Both allocated and un-allocated bytes.\n (concatenate 'vector (subseq (contents (byte-interval obj)) start)\n (make-array (- end real-end) :initial-element 0)))\n (t ; Un-allocated bytes, zero-fill.\n (make-array (size obj) :initial-element 0)))))))\n\n(defun shift-subseq (sequence start end)\n \"Return a copy of SEQUENCE bounded by START and END.\"\n (subseq sequence start end))\n\n(defparameter *preserve-symbolic-expressions* nil\n \"When true, (setf bytes) preserves symbolic expressions\nintersecting the assigned part of the object.\")\n\n(define-setf-expander shift-subseq (sequence start end &environment env)\n \"Update the subseq of SEQUENCE bounded by START and END.\"\n (multiple-value-bind (dummies vals newval setter getter)\n (get-setf-expansion sequence env)\n (declare (ignorable newval setter))\n (let ((store (gensym)))\n (values\n dummies ; Temporary variables\n vals ; Value forms.\n (list store) ; Store variables.\n `(progn\n (cond\n ((zerop ,start)\n (setf ,getter\n (concatenate 'vector ,store (subseq ,getter ,end))))\n ((= (length ,store) (- ,end ,start))\n (setf (subseq ,getter ,start ,end) ,store))\n ((>= ,end (length ,getter))\n (setf ,getter\n (concatenate 'vector (subseq ,getter 0 ,start) ,store)))\n (t (setf ,getter (concatenate 'vector\n (subseq ,getter 0 ,start)\n ,store\n (subseq ,getter ,end)))))\n ,store) ; Storing form.\n `(shift-subseq ,getter))))) ; Accessing form.\n\n(define-setf-expander bytes (sequence &optional (start 0) (end nil end-p)\n &environment env)\n (multiple-value-bind (dummies vals newval setter getter)\n (get-setf-expansion sequence env)\n (declare (ignorable newval setter))\n (let ((store (gensym))\n (end (if end-p end `(length (bytes ,getter)))))\n (values\n dummies ; Temporary variables\n vals ; Value forms.\n (list store) ; Store variables.\n `(progn\n (etypecase ,getter\n (gtirb::byte-interval\n (setf (shift-subseq (contents ,getter) ,start ,end) ,store))\n (gtirb::gtirb-byte-block\n (with-slots (offset) ,getter\n (let ((original-offset offset))\n (setf (shift-subseq (contents (byte-interval ,getter))\n (+ offset ,start) (+ offset ,end))\n ,store)\n (setf-bytes-after ,store (byte-interval ,getter)\n (+ offset ,start) (+ offset ,end))\n ;; Ensure the offset for THIS block isn't pushed back change.\n (setf offset original-offset)))))\n\n (setf-bytes-after ,store ,getter ,start ,end)\n ,store) ; Storing form.\n `(bytes ,getter))))) ; Accessing form.\n\n(defvar *update-aux-data-offsets* nil\n \"Are offsets in AuxData tables updated as bytes are modified.\")\n\n(defgeneric setf-bytes-after (new object &optional start end)\n (:documentation\n \"Update the offsets into BYTE-INTERVAL due to saving NEW into START END.\")\n (:method (new (byte-interval byte-interval)\n &optional (start 0) (end (size byte-interval)))\n (setf (size byte-interval)\n (+ start (length new) (- (size byte-interval) end)))\n (let ((difference (- (length new) (- end start))))\n ;; Symbolic expressions.\n (nest (setf (symbolic-expressions byte-interval))\n (alist-hash-table)\n (mappend (lambda (pair)\n (destructuring-bind (offset . sym-expr) pair\n (cond\n ((< offset start) (list (cons offset sym-expr)))\n ((>= offset end)\n (list (cons (+ offset difference) sym-expr)))\n ;; Clear symbolic expressions in the modified range,\n ;; unless *preserve-symbolic-expressions* is true.\n (t (if *preserve-symbolic-expressions* (list pair) nil))))))\n (hash-table-alist (symbolic-expressions byte-interval)))\n (when *update-aux-data-offsets*\n ;; Update offsets in AuxData tables.\n (labels ((update-offset (data type)\n (cond\n ((and (listp type) (eql :mapping (car type)))\n (nest (alist-hash-table)\n (mapcar «cons\n [{update-offset _ (second type)} #'car]\n [{update-offset _ (third type)} #'cdr]»)\n (hash-table-alist data)))\n ((and (listp type) (eql :sequence (car type)))\n (mapcar {update-offset _ (cdr type)} data))\n ((eql :offset type)\n ;; NOTE: Since we are already adjusting all\n ;; other code blocks and offsets are\n ;; currently stored by code block we only\n ;; need to update offsets in the current\n ;; code block.\n ;; NOTE: Offsets are relative to the base of the\n ;; code block but START is relative to the\n ;; base of the byte-interval.\n ;; NOTE: Only update offsets in the current\n ;; block.\n (let* ((obj (get-uuid (first data) byte-interval))\n (obj-start (if (typep obj 'gtirb-byte-block)\n (offset obj)\n most-positive-fixnum))\n (obj-end (+ obj-start (size obj)))\n (off (second data)))\n (when (and\n ;; Changes bytes intersect this block\n (or (and (>= obj-start start)\n (<= obj-start end))\n (and (>= obj-end start)\n (<= obj-end end)))\n ;; This offset is after the start\n ;; of the changed bytes\n (>= (+ (offset obj) off) start))\n (incf (second data) difference)))\n data)\n (t data))))\n (mapcar\n (lambda (pair)\n (let ((table (cdr pair)))\n (setf (aux-data-data table)\n (update-offset (aux-data-data table)\n (aux-data-type table)))))\n (aux-data-w-offsets (ir byte-interval)))))\n ;; Byte-Blocks.\n (mapc (lambda (bb)\n (with-slots (offset) bb\n (when (>= offset end)\n (incf offset difference))))\n (blocks byte-interval)))\n new)\n (:method (new (bb gtirb-byte-block) &optional (start 0) (end (size bb)))\n ;; Update the size of the byte-block\n (setf (size bb) (+ start (length new) (- (size bb) end)))\n new))\n\n(define-proto-backed-class (code-block proto:code-block) (gtirb-byte-block)\n ((offset :initarg :offset :accessor offset :type number\n :documentation\n \"Offset into this block's bytes in the block's byte-interval.\"))\n ((size :type unsigned-byte-64\n :documentation \"The length of the bytes held by this code block.\")\n (decode-mode :type unsigned-byte-64 :documentation\n \"Only present on architecture with multiple decode-modes.\"))\n (:documentation \"Code-block in a GTIRB IR instance.\") (:parent byte-interval)\n (:address-range (when-let ((range (address-range (byte-interval self))))\n (list (+ (offset self) (first range))\n (+ (offset self) (size self) (first range))))))\n\n(defmethod print-object ((obj code-block) stream)\n (print-unreadable-object (obj stream :type t :identity t)\n (format stream \"~a ~a\" (size obj) (decode-mode obj))))\n\n(defgeneric entry-point (module)\n (:documentation \"The code-block which is the entry point of MODULE.\")\n (:method ((obj module))\n (get-uuid (uuid-to-integer (proto:entry-point (proto obj))) obj)))\n\n(defmethod (setf entry-point) ((new code-block) (obj module))\n (proto:clear-entry-point (proto obj))\n (setf (proto:entry-point (proto obj)) (integer-to-uuid (uuid new))))\n\n(define-proto-backed-class (data-block proto:data-block) (gtirb-byte-block)\n ((offset :initarg :offset :accessor offset :type number\n :documentation\n \"Offset into this block's bytes in the block's byte-interval.\"))\n ((size :type unsigned-byte-64 :documentation\n \"The length of the bytes held by this data block.\"))\n (:documentation \"Data-block in a GTIRB IR instance.\")\n (:parent byte-interval)\n (:address-range (when-let ((range (address-range (byte-interval self))))\n (list (+ (offset self) (first range))\n (+ (offset self) (size self) (first range))))))\n\n(defmethod print-object ((obj data-block) stream)\n (print-unreadable-object (obj stream :type t :identity t)\n (format stream \"~a\" (size obj))))\n\n(define-proto-backed-class (proxy-block proto:proxy-block) (gtirb-block) () ()\n (:documentation \"Proxy-block in a GTIRB IR instance.\")\n (:parent module))\n\n(defmethod print-object ((obj proxy-block) stream)\n (print-unreadable-object (obj stream :type t :identity t)))\n\n\f\n;;;; AuxData type and data handling.\n(define-proto-backed-class (aux-data proto:aux-data) () () ())\n\n(defmethod print-object ((obj aux-data) stream)\n (print-unreadable-object (obj stream :type t :identity t)\n (format stream \"~a\" (aux-data-type obj))))\n\n(defun aux-data-from-proto (proto)\n (let ((p-aux-data (proto:aux-data proto))\n (aux-data '()))\n (dotimes (n (length p-aux-data))\n (push (cons (pb:string-value (proto:key (aref p-aux-data n)))\n (make-instance 'aux-data\n :proto (proto:value (aref p-aux-data n))))\n aux-data))\n aux-data))\n\n(defun aux-data-to-proto (aux-data)\n (map 'vector (lambda (pair)\n (destructuring-bind (name . aux-data) pair\n (let ((entry\n (make-instance 'proto:module-aux-data-entry)))\n (setf (proto:key entry) (pb:string-field name)\n (proto:value entry) (proto aux-data))\n entry)))\n aux-data))\n\n(defmacro start-case (string &body body)\n `(progn\n ;; (declare (type string ,string))\n (assert (stringp ,string) (,string) \"Argument ~s is not a string.\" ,string)\n (cond\n ,@(mapcar (lambda (form)\n (destructuring-bind (prefix . body) form\n (if (stringp prefix)\n `((eql (search ,prefix ,string) 0)\n (let ((,string (subseq ,string ,(length prefix))))\n ,@body))\n (cons prefix body))))\n body))))\n\n(defparameter +integer-typename-regex+ (create-scanner \"(U?INT)([0-9]+)-T\")\n \"Regex for deconstructing an integer typename.\")\n\n(defun matching (open-char close-char string)\n \"Return the first balanced offset of CLOSE-CHAR in STRING.\nSTRING is assumed to already have one extant OPEN-CHAR which needs to\nbe matched. New instances of OPEN-CHAR must be closed by balanced\nCLOSE-CHARs before the CLOSE-CHAR matching the implicit extant\nOPEN-CHAR.\"\n (let ((offset 1))\n (dotimes (n (length string))\n (cond\n ((eql (aref string n) open-char) (incf offset))\n ((eql (aref string n) close-char) (decf offset)))\n (when (zerop offset)\n (return-from matching n))))\n (error \"Can't close (~a ~a) in ~s.\" open-char close-char string))\n\n(defun aux-data-type-read (type-string)\n (when (and type-string (not (emptyp type-string)))\n (start-case type-string\n (\"mapping<\"\n (let ((close (matching #\\< #\\> type-string)))\n (cons (cons :mapping (aux-data-type-read (subseq type-string 0 close)))\n (aux-data-type-read (subseq type-string close)))))\n (\"set<\"\n (let ((close (matching #\\< #\\> type-string)))\n (cons (cons :set (aux-data-type-read (subseq type-string 0 close)))\n (aux-data-type-read (subseq type-string close)))))\n (\"sequence<\"\n (let ((close (matching #\\< #\\> type-string)))\n (cons (cons :sequence (aux-data-type-read (subseq type-string 0 close)))\n (aux-data-type-read (subseq type-string close)))))\n (\"tuple<\"\n (let ((close (matching #\\< #\\> type-string)))\n (cons (cons :tuple (aux-data-type-read (subseq type-string 0 close)))\n (aux-data-type-read (subseq type-string close)))))\n (\"variant<\"\n (let ((close (matching #\\< #\\> type-string)))\n (cons (cons :variant (aux-data-type-read (subseq type-string 0 close)))\n (aux-data-type-read (subseq type-string close)))))\n (\",\" (aux-data-type-read type-string))\n (\">\" (aux-data-type-read type-string))\n (\"UUID\" (cons :uuid (aux-data-type-read type-string)))\n (\"Addr\" (cons :addr (aux-data-type-read type-string)))\n (\"Offset\" (cons :offset (aux-data-type-read type-string)))\n (\"string\" (cons :string (aux-data-type-read type-string)))\n (\"bool\" (cons :bool (aux-data-type-read type-string)))\n (\"uint8_t\" (cons :uint8-t (aux-data-type-read type-string)))\n (\"uint16_t\" (cons :uint16-t (aux-data-type-read type-string)))\n (\"uint32_t\" (cons :uint32-t (aux-data-type-read type-string)))\n (\"uint64_t\" (cons :uint64-t (aux-data-type-read type-string)))\n (\"int8_t\" (cons :int8-t (aux-data-type-read type-string)))\n (\"int16_t\" (cons :int16-t (aux-data-type-read type-string)))\n (\"int32_t\" (cons :int32-t (aux-data-type-read type-string)))\n (\"int64_t\" (cons :int64-t (aux-data-type-read type-string)))\n (\"float\" (cons :float (aux-data-type-read type-string)))\n (\"double\" (cons :double (aux-data-type-read type-string)))\n (t (error \"Junk in type string ~a\" type-string)))))\n\n(defgeneric aux-data-type (aux-data)\n (:documentation \"Access the structured type of AUX-DATA.\")\n (:method ((obj aux-data))\n (first (aux-data-type-read\n (pb:string-value (proto:type-name (proto obj)))))))\n\n(defun aux-data-type-print (stream\n type\n &optional\n colon-modifier-supplied-p\n at-sign-modifier-supplied-p\n (repetitions 1))\n (declare (type (or null (eql t) stream string) stream))\n (declare (ignorable colon-modifier-supplied-p at-sign-modifier-supplied-p repetitions))\n (when type\n (if (listp type)\n (case (first type)\n (:mapping\n (format stream \"mapping<~/gtirb:aux-data-type-print/,~/gtirb:aux-data-type-print/>\"\n (second type)\n (third type)))\n (:set (format stream \"set<~/gtirb:aux-data-type-print/>\" (second type)))\n (:sequence (format stream \"sequence<~/gtirb:aux-data-type-print/>\" (second type)))\n (:tuple (format stream \"tuple<~{~/gtirb:aux-data-type-print/~^,~}>\" (cdr type)))\n (:variant (format stream \"variant<~{~/gtirb:aux-data-type-print/~^,~}>\" (cdr type))))\n (format stream (ecase type\n (:uuid \"UUID\")\n (:addr \"Addr\")\n (:offset \"Offset\")\n (:string \"string\")\n (:bool \"bool\")\n (:uint8-t \"uint8_t\")\n (:uint16-t \"uint16_t\")\n (:uint32-t \"uint32_t\")\n (:uint64-t \"uint64_t\")\n (:int8-t \"int8_t\")\n (:int16-t \"int16_t\")\n (:int32-t \"int32_t\")\n (:int64-t \"int64_t\")\n (:float \"float\")\n (:double \"double\"))))))\n\n(defmethod (setf aux-data-type) (new (obj aux-data))\n (setf (proto:type-name (proto obj))\n (pb:string-field (format nil \"~/gtirb::aux-data-type-print/\" new))))\n\n(defgeneric aux-data-data (aux-data)\n (:documentation \"Access the structured representation of AUX-DATAs data.\")\n (:method ((obj aux-data))\n (aux-data-decode (aux-data-type obj) (proto:data (proto obj)))))\n\n(defmethod (setf aux-data-data) (new (obj aux-data))\n (setf (proto:data (proto obj))\n (force-byte-array (aux-data-encode (aux-data-type obj) new))))\n\n(defun parse-num-bytes (num-bits-string)\n (/ (parse-integer num-bits-string) 8))\n\n(declaim (special *decode-data*))\n(defun decode (type)\n (labels ((advance (n) (setf *decode-data* (subseq *decode-data* n)))\n (decode-int (type)\n (register-groups-bind (type-signage (#'parse-num-bytes num-bytes))\n (+integer-typename-regex+ (symbol-name type))\n (prog1\n (if (string= type-signage \"UINT\")\n (octets->uint (subseq *decode-data* 0 num-bytes)\n num-bytes)\n (octets->int (subseq *decode-data* 0 num-bytes)\n num-bytes))\n (advance num-bytes)))))\n (declare (inline advance))\n (match type\n ((or :uint8-t :int8-t :uint16-t :int16-t\n :uint32-t :int32-t :uint64-t :int64-t)\n (decode-int type))\n (:float\n (decode-float32 (decode-int :uint32-t)))\n (:double\n (decode-float64 (decode-int :uint64-t)))\n (:addr\n (prog1\n (octets->uint (subseq *decode-data* 0 8) 8)\n (advance 8)))\n (:bool\n (prog1\n (not (zerop (octets->uint (subseq *decode-data* 0 1) 1)))\n (advance 1)))\n (:uuid\n (prog1 (uuid-to-integer (subseq *decode-data* 0 16)) (advance 16)))\n (:offset\n (handler-bind\n ((error\n (lambda (e)\n (declare (ignorable e))\n (let* ((offset (make-instance 'proto:offset))\n (size (pb:octet-size offset)))\n (pb:merge-from-array offset *decode-data* 0 size)\n (prog1 offset (advance size))))))\n (list (decode :uuid) (decode :uint64-t))))\n (:string\n (let ((size (decode :uint64-t)))\n (prog1 (utf-8-bytes-to-string (subseq *decode-data* 0 size))\n (advance size))))\n ((list :mapping key-t value-t)\n (let ((result (make-hash-table :test #'equal)))\n (dotimes (n (decode :uint64-t) result)\n (declare (ignorable n))\n (let* ((key (decode key-t))\n (value (decode value-t)))\n (setf (gethash key result) value)))))\n ((list (or :sequence :set) type)\n (let (result)\n (reverse\n (dotimes (n (decode :uint64-t) result)\n (declare (ignorable n))\n (push (decode type) result)))))\n ((list* :tuple types)\n (mapcar #'decode types))\n ((list* :variant types)\n (let ((index (decode :uint64-t)))\n (cons index (decode (nth index types))))))))\n(defun aux-data-decode (type data)\n (let ((*decode-data* data))\n (decode type)))\n\n(defun encode (type data)\n (labels ((extend (it) (push it *decode-data*))\n (encode-int (type data)\n (register-groups-bind (_ (#'parse-num-bytes num-bytes))\n (+integer-typename-regex+ (symbol-name type))\n (declare (ignorable _))\n (extend (int->octets data num-bytes)))))\n (declare (inline extend))\n (match type\n ((or :uint8-t :int8-t :uint16-t :int16-t\n :uint32-t :int32-t :uint64-t :int64-t)\n (encode-int type data))\n (:float\n (encode-int :uint32-t (encode-float32 data)))\n (:double\n (encode-int :uint64-t (encode-float64 data)))\n (:addr\n (extend (int->octets data 8)))\n (:bool\n (extend (int->octets (if data 1 0) 1)))\n (:uuid\n (extend (integer-to-uuid data)))\n (:offset\n (etypecase data\n (proto:offset\n (let* ((size (pb:octet-size data))\n (buffer (make-array size :element-type '(unsigned-byte 8))))\n (pb:serialize data buffer 0 size)\n (extend buffer)))\n (list\n (progn (encode :uuid (first data))\n (encode :uint64-t (second data))))))\n (:string\n (let ((string-bytes (string-to-utf-8-bytes data)))\n (encode :uint64-t (length string-bytes))\n (extend string-bytes)))\n ((list :mapping key-t value-t)\n (encode :uint64-t (hash-table-count data))\n (maphash (lambda (key value)\n (encode key-t key)\n (encode value-t value))\n data))\n ((list (or :sequence :set) type)\n (let ((size (length data)))\n (encode :uint64-t size)\n (dotimes (n size)\n (encode type (elt data n)))))\n ((list* :tuple types)\n (mapc (lambda (type datum)\n (encode type datum))\n types data))\n ((list* :variant types)\n (encode :uint64-t (car data))\n (encode (nth (car data) types) (cdr data))))))\n(defun aux-data-encode (type data)\n (let ((*decode-data* nil))\n (encode type data)\n (reduce {concatenate 'vector} (reverse *decode-data*))))\n" }, { "path": "cl/package.lisp", "content": "(defpackage :gtirb\n (use-package :common-lisp))\n" }, { "path": "cl/ranged.lisp", "content": "(defpackage :gtirb/ranged\n (:use :common-lisp)\n (:import-from :interval)\n (:export :make-ranged\n :ranged-insert\n :ranged-delete\n :ranged-find\n :ranged-find-at))\n(in-package :gtirb/ranged)\n#-debug (declaim (optimize (speed 3) (safety 0) (debug 0)))\n#+debug (declaim (optimize (speed 0) (safety 3) (debug 3)))\n\n(defun make-ranged ()\n (interval:make-tree))\n\n(defstruct (uuid-interval (:include interval:interval))\n (uuid 0 :type integer))\n\n(defun uuid-interval= (i1 i2)\n (= (uuid-interval-uuid i1) (uuid-interval-uuid i2)))\n\n(defun ranged-insert (tree uuid start end)\n (interval:insert tree (make-uuid-interval :uuid uuid\n :start start\n :end end)))\n\n(defun ranged-delete (tree uuid start end)\n (interval:delete tree (make-uuid-interval :uuid uuid\n :start start\n :end end)))\n\n(defun ranged-find-at (tree address)\n (mapcar #'uuid-interval-uuid\n (remove-if-not (lambda (i)\n (= address (interval:interval-start i)))\n (interval:find-all tree address))))\n\n(defun ranged-find (tree start &optional (end start))\n (mapcar #'uuid-interval-uuid (interval:find-all tree (cons start end))))\n" }, { "path": "cl/test.lisp", "content": "(defpackage :gtirb/test\n (:use :common-lisp\n :alexandria\n :flexi-streams\n :stefil\n :gtirb\n :gtirb/dot\n :gtirb/utility\n :gtirb/ranged\n :gtirb/version\n :graph\n :named-readtables :curry-compose-reader-macros)\n (:import-from :trivial-package-local-nicknames :add-package-local-nickname)\n (:import-from :gtirb.proto)\n (:import-from :gtirb/utility :check-magic-header :write-magic-header)\n (:import-from :md5 :md5sum-file :md5sum-sequence)\n (:import-from :uiop :nest :run-program :with-temporary-file :quit)\n (:import-from :asdf/system :system-relative-pathname)\n (:shadowing-import-from :gtirb :symbol)\n (:export :test :batch-test))\n(in-package :gtirb/test)\n(in-readtable :curry-compose-reader-macros)\n\n(eval-when (:compile-toplevel :load-toplevel :execute)\n (add-package-local-nickname :proto :gtirb.proto))\n\n(defvar *proto-path* nil \"Path to protobuf.\")\n\n(defun batch-test (&optional args)\n \"Run tests in 'batch' mode printing results to STDERR then quit.\nThe ERRNO used when exiting lisp indicates success or failure.\"\n (declare (ignorable args))\n (let* ((stefil::*test-progress-print-right-margin* (expt 2 20))\n (failures (coerce (stefil::failure-descriptions-of\n (without-debugging (test)))\n 'list)))\n (if failures\n (format *error-output* \"FAILURES~%~{ ~a~~%~}\"\n (mapc [#'stefil::name-of\n #'stefil::test-of\n #'car #'stefil::test-context-backtrace-of]\n failures))\n (format *error-output* \"SUCCESS~%\"))\n (quit (if failures 2 0))))\n\n(defvar *gtirb-dir* (system-relative-pathname \"gtirb\" \"../\"))\n\n\f\n;;;; Fixtures.\n(defixture hello\n (:setup\n (progn\n #+live-w-ddisasm\n (with-temporary-file (:pathname bin-path)\n (setf *proto-path* (with-temporary-file (:pathname p :keep t) p))\n (run-program (format nil \"echo 'main(){puts(\\\"hello world\\\");}'~\n |gcc -x c - -o ~a\"\n bin-path) :force-shell t)\n (run-program\n (format nil \"ddisasm --ir ~a ~a\" *proto-path* bin-path)))\n #-live-w-ddisasm\n (setf *proto-path*\n (merge-pathnames \"python/tests/hello.gtirb\" *gtirb-dir*))))\n (:teardown\n (progn\n #+live-w-ddisasm (delete-file *proto-path*)\n (setf *proto-path* nil))))\n\n\f\n;;;; Main test suite.\n(defsuite test)\n(in-suite test)\n\n(deftest we-have-versions ()\n (is (stringp gtirb-version))\n (is (integerp protobuf-version)))\n\n(deftest simple-read ()\n (with-fixture hello\n (is (eql 'proto:ir\n (class-name (class-of (read-proto 'proto:ir *proto-path*)))))))\n\n(deftest simple-write ()\n (with-fixture hello\n (with-temporary-file (:pathname path)\n (gtirb::write-proto (read-proto 'proto:ir *proto-path*) path)\n (is (probe-file path)))))\n\n(deftest idempotent-read-write ()\n (with-fixture hello\n (with-temporary-file (:pathname path)\n (gtirb::write-proto (read-proto 'proto:ir *proto-path*) path)\n ;; Protobuf provides multiple options for serializing repeated\n ;; enums, so this check can fail even with valid serialization.\n #+inhibited\n (is (equalp (md5sum-file *proto-path*)\n (md5sum-file path))))))\n\n(deftest read-gtirb-from-streams-and-files ()\n (with-fixture hello\n (is (typep (read-gtirb *proto-path*) 'gtirb))\n (is (typep (read-gtirb (namestring *proto-path*)) 'gtirb))\n (is (typep (with-open-file (input *proto-path*) (read-gtirb input))\n 'gtirb))))\n\n(deftest idempotent-read-write-w-class ()\n (nest\n (with-fixture hello)\n (with-temporary-file (:pathname path))\n (let ((hello1 (read-gtirb *proto-path*)))\n (write-gtirb hello1 path)\n (is (is-equal-p hello1 (read-gtirb path))))))\n\n(deftest idempotent-aux-data-type ()\n (with-fixture hello\n (let ((it (read-gtirb *proto-path*)))\n (is (tree-equal\n (mapcar [#'pb:string-value #'proto:type-name #'gtirb::proto #'cdr]\n (aux-data (first (modules it))))\n (mapcar [{format nil \"~/gtirb::aux-data-type-print/\"} #'aux-data-type #'cdr]\n (aux-data (first (modules it))))\n :test #'string=)))))\n\n(deftest idempotent-aux-data-decode-encode ()\n (let ((type1 '(:tuple :uuid :uint64-t :int64-t :uint64-t))\n (type2 '(:sequence :uuid))\n (type3 '(:sequence (:variant :uuid :string)))\n (data '(1 2 3 4))\n (data2 '((0 . 1) (1 . \"foo\") (0 . 3) (1 . \"bar\"))))\n (is (equalp\n (gtirb::aux-data-decode type1 (gtirb::aux-data-encode type1 data))\n data))\n (is (equalp\n (gtirb::aux-data-decode type2 (gtirb::aux-data-encode type2 data))\n data))\n (is (equalp\n (gtirb::aux-data-decode type3 (gtirb::aux-data-encode type3 data2))\n data2)))\n (with-fixture hello\n (let ((hello (read-gtirb *proto-path*)))\n (mapc (lambda (pair)\n (destructuring-bind (name . aux-data) pair\n (let* ((orig (proto:data (gtirb::proto aux-data)))\n (type (aux-data-type aux-data))\n (new (gtirb::aux-data-encode\n type (aux-data-data aux-data))))\n (is (equalp (gtirb::aux-data-decode type new)\n (gtirb::aux-data-decode type orig))\n \"~s with type ~a encodes/decodes is not idempotent~%~s\"\n name (aux-data-type aux-data)\n (list (gtirb::aux-data-decode type orig)\n (gtirb::aux-data-decode type new))))))\n (aux-data (first (modules hello)))))))\n\n(deftest test-check-magic-header ()\n (is (signals gtirb-magic-error\n (check-magic-header #())))\n (is (signals gtirb-magic-error\n (check-magic-header #(0 0 0 0 0 0 0 0))))\n (is (signals gtirb-magic-error\n (check-magic-header #(71 84 73 82 66 0 0 0))))\n (is (null (check-magic-header (vector 71 84 73 82 66 0 0 protobuf-version)))))\n\n(deftest test-write-magic-header ()\n (with-output-to-sequence (out)\n (write-magic-header out)\n (is (equalp (get-output-stream-sequence out)\n (vector 71 84 73 82 66 0 0 protobuf-version)))))\n\n(deftest update-proto-to-disk-and-back ()\n (nest\n (with-fixture hello)\n (with-temporary-file (:pathname path))\n (let ((test-string \"this is a test\")\n (hello (read-gtirb *proto-path*))\n (aux (make-instance 'aux-data)))\n (setf (aux-data-type aux) :string)\n (setf (aux-data-data aux) test-string)\n (push (cons \"test\" aux) (aux-data (first (modules hello))))\n (write-gtirb hello path)\n (let* ((next (read-gtirb path))\n (proto (gtirb::proto (first (modules next)))))\n ;; Test for non-empty protobuf elements.\n (is (not (zerop (length (proto:byte-intervals (aref (proto:sections proto) 0))))))\n ;; Test for the aux-data table created earlier in the test.\n (is (string= (aux-data-data\n (cdr (assoc \"test\" (aux-data (first (modules next)))\n :test #'string=)))\n test-string))))))\n\n(deftest create-module-with-a-name ()\n (is (string= \"foo\"\n (nest\n (pb:string-value)\n (proto:name)\n (gtirb::proto)\n (make-instance 'module :name \"foo\" :allow-other-keys t)))))\n\n;; FIXME: create-module-without-a-name should verify that the appropriate\n;; warning is emitted, but for some reason the warning doesn't percolate up\n;; to the point where the signals testing macro is able to catch it.\n(deftest create-module-without-a-name ()\n (is (emptyp (nest\n (pb:string-value)\n (proto:name)\n (gtirb::proto)\n (make-instance 'module)))))\n\n(deftest entry-points-on-modules ()\n (with-fixture hello\n (let* ((hello (read-gtirb *proto-path*))\n (module (first (modules hello)))\n (code-block (nest (first)\n (remove-if-not {typep _ 'code-block})\n (blocks hello))))\n ;; Entry-point is read as a code block.\n (is (typep (entry-point module) 'code-block))\n ;; Newly saved entry-point has the UUID of the code block.\n (setf (entry-point module) code-block)\n (is (= (uuid code-block)\n (uuid-to-integer (proto:entry-point (gtirb::proto module))))))))\n\n(deftest back-pointers-work ()\n (with-fixture hello\n (let ((hello (read-gtirb *proto-path*)))\n ;; Modules point to IR.\n (is (every [{eql hello} #'gtirb] (modules hello)))\n ;; Sections point to modules.\n (mapc (lambda (module)\n (is (every [{eql module} #'module] (sections module)))\n ;; Byte-intervals point to sections.\n (mapc (lambda (section)\n (is (every [{eql section} #'section]\n (byte-intervals section)))\n ;; Blocks point to byte-intervals.\n (mapc (lambda (byte-interval)\n (is (every [{eql byte-interval} #'byte-interval]\n (blocks byte-interval))))\n (byte-intervals section)))\n (sections module)))\n (modules hello)))))\n\n(deftest access-block-bytes ()\n (with-fixture hello\n (is (every [#'not #'null #'bytes]\n (blocks (read-gtirb *proto-path*))))))\n\n(deftest find-every-block-in-the-module ()\n (nest (with-fixture hello)\n (let ((it (read-gtirb *proto-path*))))\n (is)\n (every {get-uuid _ it})\n (mapcar #'uuid)\n (blocks it)))\n\n(deftest get-blocks-and-bytes-from-cfg-nodes ()\n (nest (with-fixture hello)\n (let ((it (read-gtirb *proto-path*))))\n (is)\n (every {get-uuid _ it})\n (nodes)\n (cfg it)))\n\n(deftest shift-subseq-adds-and-removes-as-expected ()\n (let ((it #(1 2 3 4 5)))\n (setf (gtirb::shift-subseq it 2 3) #(9 9 9 9))\n (is (equalp it #(1 2 9 9 9 9 4 5))))\n (let ((it #(1 2 3 4 5)))\n (setf (gtirb::shift-subseq it 2 3) #())\n (is (equalp it #(1 2 4 5)))))\n\n(deftest set-block-bytes-to-the-same-size ()\n (with-fixture hello\n (let* ((it (read-gtirb *proto-path*))\n (original-byte-intervals (nest (mappend #'byte-intervals)\n (mappend #'sections)\n (modules it)))\n (original-byte-interval-md5sum\n (nest (md5sum-sequence)\n (force-byte-array)\n (apply #'concatenate 'vector)\n (mapcar #'contents original-byte-intervals))))\n (let ((target (first (mappend #'blocks original-byte-intervals))))\n (setf (bytes target)\n (make-array (length (bytes target)) :initial-element 9))\n (is (= (length original-byte-intervals) ; No new byte intervals.\n (length (nest (mappend #'byte-intervals)\n (mappend #'sections)\n (modules it)))))\n (is (not (equalp original-byte-interval-md5sum ; New contents.\n (nest (md5sum-sequence)\n (force-byte-array)\n (apply #'concatenate 'vector)\n (mapcar #'contents)\n (mappend #'byte-intervals)\n (mappend #'sections)\n (modules it)))))))))\n\n(deftest set-block-bytes-to-the-different-size ()\n (with-fixture hello\n (let* ((it (read-gtirb *proto-path*))\n (original-byte-intervals (nest (mappend #'byte-intervals)\n (mappend #'sections)\n (modules it)))\n (target (first (mappend #'blocks original-byte-intervals)))\n (original-bi-size (size (byte-interval target)))\n (original-bi-bytes (bytes (byte-interval target)))\n (original-size (length (bytes target)))\n (rest-block-bytes\n (cdr (mapcar #'bytes (blocks (byte-interval target))))))\n (setf (bytes target) (make-array (* 2 original-size) :initial-element 9))\n ;; First block bytes are updated.\n (is (equalp (bytes (first (mappend #'blocks original-byte-intervals)))\n (make-array (* 2 original-size) :initial-element 9)))\n ;; Block size is updated.\n (is (equalp (size target) (* 2 original-size)))\n ;; Byte-interval size is updated.\n (is (equalp (size (byte-interval target))\n (+ original-bi-size original-size)))\n ;; Remainder of the byte-interval's bytes are the same.\n (is (equalp (subseq (bytes (byte-interval target)) (* 2 original-size))\n (subseq original-bi-bytes original-size)))\n ;; Remaining blocks bytes are the same.\n (is (every #'equalp\n rest-block-bytes\n (cdr (mapcar #'bytes (blocks (byte-interval target)))))))))\n\n(deftest address-range-block-lookup ()\n (with-fixture hello\n (let* ((it (read-gtirb *proto-path*))\n (a-block (first (blocks it))))\n (is (= 2 (length (address-range a-block))))\n (is (member a-block (nest (mappend #'blocks)\n (on-address it)\n (first)\n (address-range a-block))))\n (is (member a-block (nest (mappend #'blocks)\n (at-address it)\n (first)\n (address-range a-block))))\n (is (not (member a-block (nest (mappend #'blocks)\n (at-address it)\n (second)\n (address-range a-block))))))))\n\n(deftest symbolic-expressions-pushed-back ()\n (with-fixture hello\n ;; Collect a byte-interval with offset symbolic expressions.\n (let* ((bi (nest (find-if [{some [#'not #'zerop #'car]}\n #'hash-table-alist #'symbolic-expressions])\n (cdr) (mappend #'byte-intervals)\n (sections) (first) (modules)\n (read-gtirb *proto-path*)))\n (original-length (length (bytes bi)))\n (original-offsets (hash-table-keys (symbolic-expressions bi)))\n (largest-offset (extremum original-offsets #'>))\n (smallest-offset (extremum original-offsets #'<)))\n ;; Add bytes after the last symbol.\n (setf (bytes bi largest-offset largest-offset)\n (make-array 2 :initial-element 9))\n ;; Ensure bytes have been altered.\n (is (> (length (bytes bi)) original-length))\n ;; Ensure symbolic expressions before last have not moved.\n (is (set-equal (remove (+ largest-offset 2)\n (hash-table-keys (symbolic-expressions bi)))\n (remove largest-offset original-offsets)))\n ;; Remove those added bytes\n (setf (bytes bi largest-offset (+ largest-offset 2)) #())\n ;; Add bytes at the beginning.\n (setf (bytes bi 0 0) (make-array 1 :initial-element 9))\n ;; Ensure symbolic expressions have actually been pushed back.\n (is (set-equal (mapcar #'1+ original-offsets)\n (hash-table-keys (symbolic-expressions bi))))\n ;; Drop bytes at the beginning.\n (setf (bytes bi 0 (1+ smallest-offset)) #())\n ;; Ensure this symbolic expression now starts at the beginning.\n (is (zerop (extremum (hash-table-keys (symbolic-expressions bi))\n #'<))))))\n\n(defvar *listing-comments*)\n(defun get-listing-comments (it)\n (when-let ((table (assoc \"comments\" (gtirb::aux-data-w-offsets (ir it))\n :test #'equalp)))\n (hash-table-alist (aux-data-data (cdr table)))))\n(defmethod listing :around (object &key stream comments)\n (declare (ignorable stream comments))\n (let ((*listing-comments* (if (boundp '*listing-comments*)\n *listing-comments*\n (get-listing-comments object))))\n (call-next-method)))\n(defgeneric listing (OBJECT &key stream comments)\n (:documentation \"Print a listing of OBJECT.\")\n (:method ((self gtirb) &key (stream t) comments)\n (format stream \"~&IR~%\")\n (mapc {listing _ :stream stream :comments comments} (modules self)))\n (:method ((self module) &key (stream t) comments)\n (format stream \"~&Module: ~S~%\" (name self))\n (mapc {listing _ :stream stream :comments comments} (sections self)))\n (:method ((self section) &key (stream t) comments)\n (format stream \"~&Section: ~S\" (name self))\n (mapc {listing _ :stream stream :comments comments} (byte-intervals self)))\n (:method ((self byte-interval) &key (stream t) comments)\n (format stream \"~:[ (no address)~; at ~a~]~%\" (addressp self) (address self))\n (mapc {listing _ :stream stream :comments comments} (blocks self)))\n (:method ((self gtirb-byte-block) &key (stream t) comments)\n (let ((bytes (bytes self))\n (comments (when comments\n (remove-if-not [{= (uuid self)} #'caar] *listing-comments*))))\n (dotimes (step (size self))\n (format stream (if (zerop step) \"~&>\" \" \"))\n (if-let ((comment (and comments (find-if [{= step} #'cadar] comments))))\n (format stream \"~4X ; ~A~%\" (aref bytes step) (cdr comment))\n (format stream \"~4X\" (aref bytes step)))\n (when (= 7 (mod step 8)) (format stream \"~&\"))))))\n\n(defun block-comments (data-block it)\n (sort (nest (remove-if-not [{= (uuid data-block)} #'caar])\n (hash-table-alist)\n (aux-data-data) (cdr)\n (assoc \"comments\" (gtirb::aux-data-w-offsets (ir it))\n :test #'equalp))\n #'< :key [#'second #'car]))\n\n(deftest offsets-pushed-back ()\n (nest (let ((gtirb::*update-aux-data-offsets* t)))\n (with-fixture hello)\n (let* ((it (read-gtirb *proto-path*))\n (text (find-if [{string= \".text\"} #'name]\n (sections (first (modules it)))))\n (commented-block (find-if {block-comments _ it} (blocks text)))\n (comment (first (block-comments commented-block it)))\n (starting-offset (cadar comment)))\n (is (gtirb::get-aux-data-w-offsets it)\n \"We're finding aux-data tables with offsets. ~\n Should be at least comments and cfiDirectives.\")\n (is (gtirb::aux-data-w-offsets it)\n \"The `aux-data-w-offsets' was populated.\")\n #+nil (listing commented-block :comments t)\n (setf (bytes commented-block 0 0) #(0 0 0 0))\n #+nil (listing commented-block :comments t)\n (is (= (+ 4 starting-offset)\n (cadar (first (block-comments commented-block it))))))))\n\n(deftest block-symbolic-expressions ()\n (with-fixture hello\n (is (nest (mappend [#'hash-table-values #'symbolic-expressions])\n (mappend #'blocks) (mappend #'byte-intervals)\n (sections) (first) (modules)\n (read-gtirb *proto-path*)))))\n\n(deftest symbolic-expressions-maintained ()\n (nest\n (with-fixture hello)\n (mapc (lambda (db)\n (let ((o-offset (offset db))\n (o-bi-size (size (byte-interval db)))\n (o-db-size (size db))\n (o-bi-se-size (hash-table-size\n (symbolic-expressions (byte-interval db))))\n (o-se-size (hash-table-size\n (symbolic-expressions db))))\n (setf (bytes db 0 0) #(#x90 #x90 #x90 #x90))\n (is (= o-offset (offset db)))\n (is (= (+ 4 o-bi-size) (size (byte-interval db))))\n (is (= (+ 4 o-db-size) (size db)))\n (is (= o-bi-se-size\n (hash-table-size\n (symbolic-expressions (byte-interval db)))))\n (is (= o-se-size\n (hash-table-size\n (symbolic-expressions db)))))))\n (blocks (read-gtirb *proto-path*))))\n\n(deftest payload-can-be-read-and-set ()\n (with-fixture hello\n (let* ((it (read-gtirb *proto-path*))\n (symbols (mappend #'symbols (modules it)))\n (referent-symbol\n (find-if [#'proto:has-referent-uuid #'gtirb::proto] symbols)))\n ;; Reading gives the right type of payload.\n (is (subtypep (type-of (payload referent-symbol)) 'gtirb::proto-backed))\n ;; Setting a payload has the right effect.\n (setf (payload referent-symbol) 42) ; Referent to value.\n (is (subtypep (type-of (payload referent-symbol)) 'number))\n (is (not (proto:has-referent-uuid (gtirb::proto referent-symbol)))))))\n\n(deftest can-create-without-parents ()\n (is (typep (make-instance 'module) 'module))\n (is (typep (make-instance 'section) 'section))\n (is (typep (make-instance 'byte-interval) 'byte-interval)))\n\n(deftest direct-ir-access ()\n (with-fixture hello\n (let* ((it (read-gtirb *proto-path*)))\n (is (typep (ir (setf it (first (modules it)))) 'gtirb))\n (is (typep (ir (setf it (first (sections it)))) 'gtirb))\n (is (typep (ir (setf it (first (byte-intervals it)))) 'gtirb))\n (is (typep (ir (setf it (first (blocks it)))) 'gtirb)))))\n\n(deftest every-symbolic-expression-has-symbols ()\n (flet ((every-symbolic-expression-has-symbols-proto (path)\n (every (lambda (se)\n (cond\n ((proto:has-addr-const se)\n (proto:symbol-uuid (proto:addr-const se)))\n ((proto:has-addr-addr se)\n (proto:symbol1-uuid (proto:addr-addr se)))))\n (nest\n (mapcar #'proto:value)\n (mappend [{coerce _ 'list} #'proto:symbolic-expressions])\n (mappend [{coerce _ 'list} #'proto:byte-intervals])\n (coerce (proto:sections\n (aref (proto:modules\n (read-proto 'proto:ir path)) 0))\n 'list))))\n (every-symbolic-expression-has-symbols-gtirb (path)\n (nest (every #'symbols)\n (mappend [#'hash-table-values #'symbolic-expressions])\n (mappend #'byte-intervals)\n (mappend #'sections)\n (modules (read-gtirb path)))))\n (with-fixture hello\n ;; First confirm for the protobuf\n (is (every-symbolic-expression-has-symbols-proto *proto-path*))\n ;; Second confirm for the GTIRB representation.\n (is (every-symbolic-expression-has-symbols-gtirb *proto-path*))\n ;; Then re-confirm both for a rewritten protobuf file.\n (uiop:with-temporary-file (:pathname temporary-file)\n (write-gtirb (read-gtirb *proto-path*) temporary-file)\n (is (every-symbolic-expression-has-symbols-proto temporary-file))\n (is (every-symbolic-expression-has-symbols-gtirb temporary-file))))))\n\n#+ignore-expected-failure\n(deftest every-block-is-found-at-its-address ()\n (with-fixture hello\n (let ((it (read-gtirb *proto-path*)))\n (nest (is)\n (every «member #'identity [{at-address it} #'address]»)\n (mappend #'blocks)\n (mappend #'byte-intervals)\n (mappend #'sections)\n (modules it)))))\n\n(deftest truncating-size-on-byte-interval-errors-and-truncates ()\n (with-fixture hello\n (let ((byte-intervals (nest (mappend #'byte-intervals)\n (mappend #'sections)\n (modules)\n (read-gtirb *proto-path*))))\n ;; Truncation signals an error.\n (signals ir\n (setf (size (first byte-intervals))\n (1- (length (contents (first byte-intervals))))))\n ;; Truncate restart works.\n (let* ((bi (second byte-intervals))\n (original-length (length (contents bi))))\n (handler-bind\n ((ir\n (lambda (e)\n (if (find-restart 'truncate-contents)\n (invoke-restart 'truncate-contents)\n (error e)))))\n (setf (size bi) (1- original-length)))\n (is (= original-length\n (+ 1 (size bi))\n (+ 1 (length (contents bi))))))\n ;; Ignore restart works.\n (let* ((bi (third byte-intervals))\n (original-length (length (contents bi))))\n (handler-bind\n ((ir\n (lambda (e)\n (if (find-restart 'ignore)\n (invoke-restart 'ignore)\n (error e)))))\n (setf (size bi) (1- original-length)))\n (is (= original-length (length (contents bi))))\n (is (> original-length (size bi)))))))\n\n\f\n;;;; Dot test suite\n(deftest write-dot-to-file ()\n (with-fixture hello\n (with-temporary-file (:pathname path)\n (to-dot-file (read-gtirb *proto-path*) path))))\n" }, { "path": "cl/update.lisp", "content": "(defpackage :gtirb/update\n (:use :common-lisp\n :alexandria\n :gtirb/utility\n :named-readtables\n :curry-compose-reader-macros\n :command-line-arguments)\n (:import-from :serapeum :take-while)\n (:import-from :gtirb.proto)\n (:import-from :trivial-package-local-nicknames :add-package-local-nickname)\n (:import-from :proto-v0)\n (:import-from :uiop :nest)\n (:import-from :uiop/image :quit)\n (:import-from :gtirb\n :aux-data :aux-data-type :aux-data-data\n :+module-file-format-map+)\n (:export :update :upgrade :read-proto :write-proto))\n(in-package :gtirb/update)\n(in-readtable :curry-compose-reader-macros)\n\n(eval-when (:compile-toplevel :load-toplevel :execute)\n (add-package-local-nickname :proto :gtirb.proto)\n (defparameter +udpate-args+\n '(((\"help\" #\\h #\\?) :type boolean :optional t\n :documentation \"display help output\"))))\n\n(defun module-bytes-subseq (module start end &aux (results #()))\n (let ((regions (proto-v0:regions (proto-v0:byte-map\n (proto-v0:image-byte-map module)))))\n (force-byte-array\n (dotimes (n (length regions) results)\n (let* ((region (aref regions n))\n (address (proto-v0:address region))\n (size (length (proto-v0:data region))))\n (cond\n ((and (<= address start) (< start (+ address size)))\n (setf results (concatenate 'vector\n results\n (subseq (proto-v0:data region)\n (- start address)\n (min size (- end address)))))\n (setf start (min end (+ address size))))\n ((= start end) (return results))))))))\n\n(defun byte-interval (module section\n &aux (new (make-instance 'proto:byte-interval)))\n (let ((address (proto-v0:address section))\n (size (proto-v0:size section)))\n (setf (proto:uuid new) (new-uuid)\n (proto:address new) address\n (proto:has-address new) (proto-v0:has-address section)\n (proto:size new) size\n (proto:contents new)\n (module-bytes-subseq module address (+ address size))\n (proto:symbolic-expressions new)\n (map 'vector {upgrade _ :base address}\n (remove-if-not [«and {<= address} {>= (+ address size)}» #'proto-v0:key]\n (proto-v0:symbolic-operands module)))\n (proto:blocks new)\n (map 'vector (lambda (block)\n (etypecase block\n (proto-v0:block\n (let ((it (make-instance 'proto:block)))\n (setf (proto:code it)\n (upgrade block)\n (proto:offset it)\n (- (proto-v0:address block) address))\n it))\n (proto-v0:data-object\n (let ((it (make-instance 'proto:block)))\n (setf (proto:data it)\n (upgrade block :base address)\n (proto:offset it)\n (- (proto-v0:address block) address))\n it))))\n (remove-if-not\n (lambda (block)\n (let ((addr (proto-v0:address block)))\n (and (<= address addr)\n (< addr (+ address size)))))\n (concatenate 'vector\n (proto-v0:blocks module)\n (proto-v0:data module))))))\n (coerce (list new) 'vector))\n\n(defun entry-point (module)\n (when-let ((address (proto-v0:entry-point-address\n (proto-v0:image-byte-map module))))\n (if-let ((gtirb-block\n (find-if\n «and [{< address} «+ #'proto-v0:address #'proto-v0:size»]\n [{>= address} #'proto-v0:address]»\n (proto-v0:blocks module))))\n (proto-v0:uuid gtirb-block)\n (if (zerop address)\n (warn \"Zero address found in module ~S, assuming not an entry point.\"\n (pb:string-value (proto-v0:name module)))\n (error \"No block found holding module ~S entry point ~a.\"\n (pb:string-value (proto-v0:name module))\n address)))))\n\n(defmacro transfer-fields (new old &rest fields)\n `(progn\n ,@(mapcar (lambda (field)\n `(setf (,(intern (symbol-name field) 'proto) ,new)\n (upgrade (,(intern (symbol-name field) 'proto-v0) ,old))))\n fields)))\n\n#+debug\n(defun serial (it)\n \"Useful to ensure yourself of what protobuf serialization is producing.\"\n (let* ((size (pb:octet-size it))\n (buffer (make-array size :element-type '(unsigned-byte 8))))\n (pb:serialize it buffer 0 size)\n buffer))\n\n#+debug\n(defun deserial (class bytes &aux (it (make-instance class)))\n \"Useful to ensure yourself of what protobuf deserialization is producing.\"\n (pb:merge-from-array it bytes 0 (length bytes))\n it)\n\n(defun combine-cfgs (cfgs)\n (let ((it (make-instance 'proto:cfg)))\n (setf (proto:edges it)\n (coerce (mappend [{coerce _ 'list} #'proto:edges] cfgs) 'vector))\n (setf (proto:vertices it)\n (coerce (mappend [{coerce _ 'list} #'proto:vertices] cfgs) 'vector))\n it))\n\n(define-constant +symbol-storage-kind+\n '((#.proto-v0:+storage-kind-storage-undefined+ . :undefined)\n (#.proto-v0:+storage-kind-storage-normal+ . :normal)\n (#.proto-v0:+storage-kind-storage-static+ . :static)\n (#.proto-v0:+storage-kind-storage-extern+ . :extern)\n (#.proto-v0:+storage-kind-storage-local+ . :local))\n :test #'equal)\n\n(defvar *code-block-uuids* (make-hash-table))\n(defvar *data-block-uuids* (make-hash-table))\n\n(defun storage-kind (symbol)\n (cdr (assoc (proto-v0:storage-kind symbol) +symbol-storage-kind+)))\n\n(defun elf-symbol-info (symbol)\n \"Return an elfSymbolInfo entry for SYMBOL using its `proto-v0:storage-kind'.\"\n (list\n 0\n ;; Point to data \"OBJ,\" if it points to a code \"FUNC,\" else \"NOTYPE.\"\n (cond\n ((gethash (proto-v0:uuid symbol) *data-block-uuids*) \"OBJ\")\n ((gethash (proto-v0:uuid symbol) *code-block-uuids*) \"FUNC\")\n (t \"NOTYPE\"))\n (ecase (storage-kind symbol)\n ((:normal :static) \"GLOBAL\")\n (:local \"LOCAL\"))\n (ecase (storage-kind symbol)\n (:normal \"DEFAULT\")\n ((:local :static) \"HIDDEN\"))\n 0))\n\n(defun update-padding-table (data offset-bases)\n \"Convert DATA which is keyed by addresses to be keyed by offset.\nUse OFFSET-BASES, an alist of base address and byte-interval, to do\nthis conversion.\"\n (let* ((it (make-instance 'aux-data :proto data))\n (data (aux-data-data it)))\n (nest (setf (aux-data-type it) '(:mapping :offset :uint64-t)\n (aux-data-data it))\n (alist-hash-table)\n (mapcar (lambda (pair)\n (destructuring-bind (addr . value) pair\n (let ((base (nest (lastcar)\n (take-while [{> addr} #'car])\n offset-bases)))\n (destructuring-bind (base . id) base\n (cons\n (let ((it (make-instance 'proto:offset)))\n (setf (proto:element-id it) id)\n (setf (proto:displacement it) (- addr base))\n it)\n value))))))\n (hash-table-alist)\n data)\n (gtirb::proto it)))\n\n(defun offset-bases (new-sections)\n (nest (apply #'append)\n (map 'list (lambda (section)\n (map 'list (lambda (bi)\n (assert (proto:has-address bi))\n (cons (proto:address bi)\n (proto:uuid bi)))\n (proto:byte-intervals section))))\n new-sections))\n\n(defgeneric upgrade (object &key &allow-other-keys)\n (:documentation \"Upgrade OBJECT to the next protobuf version.\")\n (:method ((old t) &key &allow-other-keys) old)\n (:method ((old array) &key &allow-other-keys)\n (if (every #'numberp old)\n (force-byte-array old)\n (map 'vector #'upgrade old)))\n (:method ((old proto-v0:ir) &key &allow-other-keys\n &aux (new (make-instance 'proto:ir)))\n (setf (proto:uuid new) (proto-v0:uuid old)\n (proto:version new) 1\n (proto:aux-data new) (upgrade (proto-v0:aux-data-container old)\n :new-class 'proto:ir-aux-data-entry)\n (proto:modules new) (upgrade (proto-v0:modules old))\n (proto:cfg new) (combine-cfgs (map 'list [#'upgrade #'proto-v0:cfg]\n (proto-v0:modules old))))\n new)\n (:method ((old proto-v0:module) &key &allow-other-keys\n &aux (new (make-instance 'proto:module)))\n (transfer-fields new old\n uuid binary-path preferred-addr rebase-delta file-format\n name symbols proxies name)\n (let ((new-sections (map 'vector {upgrade _ :module old}\n (proto-v0:sections old))))\n (setf (proto:isa new) (proto-v0:isa-id old)\n (proto:aux-data new)\n (upgrade (proto-v0:aux-data-container old)\n :new-class 'proto:module-aux-data-entry\n :offset-bases (offset-bases new-sections))\n (proto:sections new) new-sections))\n (if-let ((entry-point (entry-point old)))\n (setf (proto:entry-point new) entry-point))\n ;; Add a symbolType AuxData table of type mapping to\n ;; track the storage kinds of all symbols.\n (ecase (cdr (assoc (proto-v0:file-format old) +module-file-format-map+))\n (:elf\n (let ((ad (make-instance 'aux-data))\n (ade (make-instance 'proto:module-aux-data-entry)))\n (setf (aux-data-type ad)\n '(:mapping :uuid\n (:tuple :uint64-t :string :string :string :uint64-t))\n (aux-data-data ad)\n (alist-hash-table\n (map 'list «cons [#'uuid-to-integer #'proto-v0:uuid]\n #'elf-symbol-info»\n (remove-if [{eql :extern} #'storage-kind]\n (proto-v0:symbols old)))))\n (setf (proto:key ade) (pb:string-field \"elfSymbolInfo\")\n (proto:value ade) (gtirb::proto ad))\n (setf (proto:aux-data new)\n (coerce (append (list ade) (coerce (proto:aux-data new) 'list))\n 'vector))))\n (:pe (flet ((symbols-to-aux-data (name symbols)\n (let ((ad (make-instance 'aux-data))\n (ade (make-instance 'proto:module-aux-data-entry)))\n (setf (aux-data-type ad) '(:set :uuid)\n (aux-data-data ad) symbols\n (proto:key ade) (pb:string-field name)\n (proto:value ade) (gtirb::proto ad))\n ade)))\n (let ((in (symbols-to-aux-data\n \"peImportedSymbols\"\n (nest\n (mapcar [#'uuid-to-integer #'proto-v0:uuid])\n (remove-if-not [{member _ '(:local :static)}\n #'storage-kind])\n (proto-v0:symbols old))))\n (out (symbols-to-aux-data\n \"peExportedSymbols\"\n (nest\n (mapcar [#'uuid-to-integer #'proto-v0:uuid])\n (remove-if-not [{member _ '(:normal :extern)}\n #'storage-kind])\n (proto-v0:symbols old)))))\n (setf (proto:aux-data new)\n (coerce (append (list in out)\n (coerce (proto:aux-data new) 'list))\n 'vector))))))\n new)\n (:method ((old proto-v0:aux-data-container) &key new-class offset-bases\n &allow-other-keys)\n (map 'vector (lambda (entry)\n (let ((it (make-instance new-class)))\n (let ((new-value (upgrade (proto-v0:value entry))))\n (when (string= \"padding\"\n (pb:string-value (proto-v0:key entry)))\n (setf new-value (update-padding-table\n new-value offset-bases)))\n (setf (proto:key it) (proto-v0:key entry)\n (proto:value it) new-value))\n it))\n (proto-v0:aux-data old)))\n (:method ((old proto-v0:aux-data) &key &allow-other-keys\n &aux (new (make-instance 'proto:aux-data)))\n (transfer-fields new old type-name data)\n new)\n (:method ((old proto-v0:section) &key module &allow-other-keys\n &aux (new (make-instance 'proto:section)))\n (transfer-fields new old uuid name)\n (setf (proto:byte-intervals new) (byte-interval module old))\n new)\n (:method ((old proto-v0:edge-label) &key &allow-other-keys\n &aux (new (make-instance 'proto:edge-label)))\n (transfer-fields new old conditional direct type)\n new)\n (:method ((old proto-v0:edge) &key &allow-other-keys\n &aux (new (make-instance 'proto:edge)))\n (transfer-fields new old source-uuid target-uuid label)\n new)\n (:method ((old proto-v0:cfg) &key &allow-other-keys\n &aux (new (make-instance 'proto:cfg)))\n (transfer-fields new old vertices edges)\n new)\n (:method ((old proto-v0:module-symbolic-operands-entry)\n &key base &allow-other-keys\n &aux (new (make-instance\n 'proto:byte-interval-symbolic-expressions-entry)))\n (setf (proto:key new) (- (proto-v0:key old) base)\n (proto:value new) (upgrade (proto-v0:value old)))\n new)\n (:method ((old proto-v0:symbol) &key &allow-other-keys\n &aux (new (make-instance 'proto:symbol)))\n (transfer-fields new old uuid name)\n (cond ; Variant \"oneof\" 'value' or 'referent_uuid'.\n ((proto-v0:has-value old)\n (setf (proto:value new) (proto-v0:value old)))\n ((proto-v0:has-referent-uuid old)\n (setf (proto:referent-uuid new) (upgrade (proto-v0:referent-uuid old))\n ;; This field was added after GTIRB-V.0.\n (proto:at-end new) nil)))\n new)\n (:method ((old proto-v0:symbolic-expression) &key &allow-other-keys\n &aux (new (make-instance 'proto:symbolic-expression)))\n (cond ; Variant \"oneof\" field.\n ((proto-v0:has-addr-const old)\n (setf (proto:addr-const new) (upgrade (proto-v0:addr-const old))))\n ((proto-v0:has-addr-addr old)\n (setf (proto:addr-addr new) (upgrade (proto-v0:addr-addr old))))\n (t (warn \"Symbolic expressions ~s has no value.\" old)))\n #+debug\n (progn ; Potentially useful debug pattern to inspect protobuf.\n (format t \"~%~%~%OLD:~S~%\" (serial old))\n (describe old)\n (format t \"~%NEW:~S~%\" (serial new))\n (describe new))\n new)\n (:method ((old proto-v0:sym-addr-const) &key &allow-other-keys\n &aux (new (make-instance 'proto:sym-addr-const)))\n (transfer-fields new old symbol-uuid)\n new)\n (:method ((old proto-v0:sym-addr-addr) &key &allow-other-keys\n &aux (new (make-instance 'proto:sym-addr-addr)))\n (transfer-fields new old scale offset symbol1-uuid symbol2-uuid)\n new)\n (:method ((old proto-v0:block) &key &allow-other-keys\n &aux (new (make-instance 'proto:code-block)))\n (setf (gethash (proto-v0:uuid old) *code-block-uuids*) t)\n (transfer-fields new old uuid size decode-mode)\n new)\n (:method ((old proto-v0:data-object) &key &allow-other-keys\n &aux (new (make-instance 'proto:data-block)))\n (setf (gethash (proto-v0:uuid old) *data-block-uuids*) t)\n (transfer-fields new old uuid size)\n new))\n\n(define-command update (input-file output-file &spec +udpate-args+)\n \"Update GTIRB protobuf from INPUT-FILE to OUTPUT-FILE.\" \"\"\n (when help (show-help-for-update) (quit))\n (setf *random-state* (make-random-state t))\n (write-proto (upgrade (read-proto 'proto-v0:ir input-file)) output-file))\n" }, { "path": "cl/utility.lisp", "content": "(defpackage :gtirb/utility\n (:use :common-lisp\n :gtirb/version)\n (:import-from :cl-intbytes\n :int->octets\n :octets->int)\n (:import-from :alexandria\n :define-constant\n :read-stream-content-into-byte-vector\n :read-file-into-byte-vector\n :starts-with-subseq)\n (:import-from :uiop :nest)\n (:import-from :uiop/stream :file-stream-p)\n (:export :read-proto\n :write-proto\n :gtirb-magic-error\n :new-uuid\n :force-byte-array\n :uuid-to-integer\n :integer-to-uuid))\n(in-package :gtirb/utility)\n(declaim (optimize (speed 3) (safety 0) (debug 0)))\n\n(define-constant gtirb-magic-octets #(71 84 73 82 66) ;; \"GTIRB\"\n :test #'equalp\n :documentation \"GTIRB file magic bytes at beginning of magic header.\")\n\n(define-constant gtirb-magic-length 8\n :test #'equal\n :documentation \"Number of bytes in the GTIRB file magic header.\")\n\n(define-condition gtirb-magic-error (error)\n ((message :initarg :message :initform nil :reader message))\n (:report (lambda (condition stream)\n (format stream \"~S\" (message condition))))\n (:documentation \"Condition raised if GTIRB header is invalid.\"))\n\n(defgeneric read-proto (class source)\n (:documentation \"Read protobuf object of class CLASS from SOURCE.\")\n (:method :before\n (class (path pathname))\n (declare (ignorable class))\n (assert (probe-file path) (path)\n \"Can't read Protobuf from ~s, because the file doesn't exist.\"\n path))\n (:method (class (path string)) (read-proto class (pathname path)))\n (:method (class (path pathname))\n (with-open-file (input path :direction :input :element-type 'unsigned-byte)\n (read-proto class input)))\n (:method (class (input stream))\n (read-proto class (if (file-stream-p input)\n (read-file-into-byte-vector input)\n (read-stream-content-into-byte-vector input))))\n (:method (class (buffer array) &aux (gtirb (make-instance class)))\n (check-magic-header buffer)\n (pb:merge-from-array gtirb buffer gtirb-magic-length (length buffer))\n gtirb))\n\n(defun write-proto (object path)\n \"Write OBJECT to PATH.\"\n (let* ((size (pb:octet-size object))\n (buffer (make-array size :element-type '(unsigned-byte 8))))\n (pb:serialize object buffer 0 size)\n (with-open-file (output path\n :direction :output :if-exists :supersede\n :element-type 'unsigned-byte)\n (write-magic-header output)\n (write-sequence buffer output)))\n (values))\n\n(defun new-uuid (&aux (it (make-array 16 :element-type '(unsigned-byte 8))))\n \"Return a new random UUID.\"\n (dotimes (n 16 it) (setf (aref it n) (random 256))))\n\n(defun force-byte-array (array)\n \"Force ARRAY into a byte array.\"\n (declare (type (simple-array) array))\n (make-array (length array) :element-type '(unsigned-byte 8)\n :initial-contents array))\n\n(defun uuid-to-integer (uuid)\n (declare (type (simple-array) uuid))\n (if (zerop (length uuid))\n (prog1 0 #+debug (warn \"Bad null UUID.\"))\n (octets->int (force-byte-array uuid) 16)))\n\n(defun integer-to-uuid (number)\n (int->octets number 16))\n\n(defun check-magic-header (bytes)\n \"Check if the GTIRB magic header bytes are present in at the start of BYTES,\nthrowing a GTIRB-MAGIC-ERROR if the header is not present.\"\n (when (or (< (length bytes) gtirb-magic-length)\n (not (starts-with-subseq gtirb-magic-octets bytes)))\n (error (make-condition 'gtirb-magic-error\n :message \"File missing GTIRB magic - not a GTIRB file?\")))\n (when (not (equal protobuf-version (aref bytes (1- gtirb-magic-length))))\n (error (nest (make-condition 'gtirb-magic-error :message)\n (format nil \"Attempt to decode IR of version ~d (expected version ~d)\"\n (aref bytes (1- gtirb-magic-length))\n protobuf-version)))))\n\n(defun write-magic-header (stream)\n \"Write the GTIRB magic header bytes to STREAM.\"\n (write-sequence gtirb-magic-octets stream)\n (write-byte 0 stream)\n (write-byte 0 stream)\n (write-byte protobuf-version stream))\n" }, { "path": "cl/validate.lisp", "content": "(defpackage :gtirb/validate\n (:use :gt/full :gtirb :graph :command-line-arguments)\n (:import-from :gtirb.proto)\n (:shadowing-import-from :gt/full :size :copy)\n (:shadowing-import-from :gtirb :symbol)\n (:export :validate))\n(in-package :gtirb/validate)\n(in-readtable :curry-compose-reader-macros)\n(defmethod size ((gtirb-node gtirb-node)) (gtirb:size gtirb-node))\n(defmethod copy ((graph graph) &key &allow-other-keys) (graph:copy graph))\n\n\f\n;;;; Interface\n(defvar *requirements* nil\n \"A-list of default requirements keyed by object type.\")\n\n(defvar *failed-checks*)\n\n(defgeneric validate (object &key requirements)\n (:documentation \"Validate that OBJECT satisfies the requirements in .\")\n (:method\n ((object t) &key (requirements *requirements*) &aux (*failed-checks* nil))\n (values (every {check object} (cdr (assoc (type-of object) requirements)))\n *failed-checks*)))\n\n(defclass check ()\n ((action :reader action :initarg :action\n :type (or symbol function) :documentation \"Action to run the check.\")\n (object :reader object :initarg :object\n :type symbol :documentation \"Type of object the check applies to.\")\n (name :reader name :initarg :name\n :type string :documentation \"Name of the check.\"))\n (:documentation \"Check objects hold validation checks for gtirb instances.\"))\n\n(defmethod initialize-instance :after\n ((check check) &key (requirements *requirements*) &allow-other-keys)\n (unless (assoc (object check) requirements)\n (push (list (object check)) requirements))\n (pushnew check (cdr (assoc (object check) requirements)) :key #'name))\n\n(defgeneric check (object requirement)\n (:documentation \"Check that OBJECT satisfies REQUIREMENT.\")\n (:method ((obj t) (requirement symbol)) (funcall requirement obj))\n (:method ((obj t) (requirement function)) (funcall requirement obj))\n (:method ((obj t) (requirement check)) (funcall (action requirement) obj)))\n\n(defmethod check :around ((object t) (requirement function))\n (or (call-next-method) (push requirement *failed-checks*)))\n(defmethod check :around ((object t) (requirement check))\n (or (call-next-method) (push (name requirement) *failed-checks*)))\n\n\f\n;;;; GTIRB Checks\n(defmacro define-check-generic (name (object) &body methods)\n `(progn (defgeneric ,name (,object) ,@methods)\n (make-instance 'check\n :name ',name\n :action ',name\n :object ',(second (first (second (first methods)))))))\n\n(define-check-generic size-matches-contents (object)\n (:method ((obj gtirb)) (every #'size-matches-contents (modules obj)))\n (:method ((obj module)) (every #'size-matches-contents (sections obj)))\n (:method ((obj section)) (every #'size-matches-contents (byte-intervals obj)))\n (:method ((obj byte-interval)) (= (size obj) (length (contents obj)))))\n\n(flet ((nothing-overlaps- (things &aux (min 0))\n (and (every (lambda (pair)\n (destructuring-bind (address . size) pair\n (prog1 (>= address min)\n (setf min (max min (+ address size))))))\n (sort (mapcar «cons #'address #'size» things) #'<\n :key #'car))\n (every #'nothing-overlaps things))))\n (define-check-generic nothing-overlaps (object)\n (:method ((obj gtirb)) (every #'nothing-overlaps (modules obj)))\n (:method ((obj module)) (nothing-overlaps- (sections obj)))\n (:method ((obj section)) (nothing-overlaps- (byte-intervals obj)))\n (:method ((obj byte-interval))\n (nothing-overlaps- (remove-if-not {typep _ 'code-block} (blocks obj))))\n (:method ((obj code-block)) t)))\n\n(define-check-generic all-referents-exist (object)\n (:method ((obj gtirb))\n (and (every #'all-referents-exist (modules obj))\n (every {get-uuid _ obj} (nodes (cfg obj)))))\n (:method ((obj module)) (every #'all-referents-exist (symbols obj)))\n (:method ((obj symbol))\n (if (gtirb.proto:has-referent-uuid (gtirb::proto obj))\n (payload obj)\n t)))\n\n(define-check-generic symbolic-expression-size-well-formed (object)\n (:method ((obj gtirb))\n (every [{every «member #'second\n [#'hash-table-keys #'symbolic-expressions\n {get-uuid _ obj} #'car]»}\n #'hash-table-keys #'aux-data-data #'cdr\n (lambda (el) (assoc \"symbolicExpressionSizes\" el :test #'string=))\n #'aux-data]\n (modules obj))))\n\n\f\n;;;; Command-line interface\n(eval-when (:compile-toplevel :load-toplevel :execute)\n (defparameter +validate-args+\n '(((\"help\" #\\h #\\?) :type boolean :optional t\n :documentation \"display help output\"))))\n\n(define-command validate-file (gtirb-file &spec +validate-args+)\n \"Validate GTIRB-FILE.\" \"\"\n (flet ((exit (code)\n (if *lisp-interaction*\n (return-from validate-file (zerop code))\n (quit code))))\n (when help (show-help-for-validate-file) (quit))\n (if (validate (read-gtirb gtirb-file))\n (exit 0)\n (exit 2))))\n" }, { "path": "cl/version.lisp", "content": "(defpackage :gtirb/version\n (:use :common-lisp)\n (:import-from :alexandria\n :define-constant)\n (:import-from :asdf/system :system-relative-pathname)\n (:import-from :uiop :nest)\n (:export :gtirb-version\n :protobuf-version))\n(in-package :gtirb/version)\n\n(eval-when (:compile-toplevel :load-toplevel :execute)\n (defvar version.txt\n `#.(nest (let ((version-path\n (system-relative-pathname \"gtirb\" \"../version.txt\"))))\n (with-open-file (in version-path))\n (loop for line = (read-line in nil :eof)\n until (eql line :eof)\n collect (let ((delim (position #\\Space line)))\n (cons (intern (subseq line 0 delim))\n (parse-integer (subseq line (1+ delim)))))))))\n\n(define-constant gtirb-version\n (format nil \"~d.~d.~d\"\n (cdr (assoc 'VERSION_MAJOR version.txt))\n (cdr (assoc 'VERSION_MINOR version.txt))\n (cdr (assoc 'VERSION_PATCH version.txt)))\n :test #'string=\n :documentation \"GTIRB Version as a string of \\\"MAJOR.MINOR.PATCH\\\".\")\n\n(define-constant protobuf-version\n (cdr (assoc 'VERSION_PROTOBUF version.txt))\n :test #'=\n :documentation \"GTIRB Protobuf Version as a non-negative integer.\")\n" }, { "path": "conanfile.py", "content": "import os\nimport re\n\nfrom conans import CMake, ConanFile, tools\nfrom conans.errors import ConanInvalidConfiguration\nfrom conans.model.version import Version\n\n\ndef get_gtirb_version():\n if \"CI_COMMIT_REF_NAME\" in os.environ:\n branch = os.environ[\"CI_COMMIT_REF_NAME\"]\n if branch == \"master\":\n return \"dev\"\n try:\n with open(\"version.txt\") as f:\n s = f.read()\n match = re.search(\n r\"VERSION_MAJOR(\\s+)(\\S+)(\\s+)\"\n r\"VERSION_MINOR(\\s+)(\\S+)(\\s+)\"\n r\"VERSION_PATCH(\\s+)(\\S+)(\\s+)\",\n s,\n )\n if match:\n major = match.group(2)\n minor = match.group(5)\n patch = match.group(8)\n return major + \".\" + minor + \".\" + patch\n else:\n return \"\"\n except Exception:\n return \"\"\n\n\ndef branch_to_channel(branch):\n if re.match(r\"^release-.*\", branch):\n return \"stable\"\n else:\n return branch.replace(\"/\", \"+\")\n\n\nclass Properties:\n name = \"gtirb\"\n rel_url = \"rewriting/gtirb\"\n exports_sources = \"*\", \"!*_CPack_Packages*\", \"!*java*.class\"\n\n @property\n def version(self):\n if not hasattr(self, \"_version\"):\n self._version = get_gtirb_version()\n return self._version\n\n @version.setter\n def version(self, ver):\n self._version = ver\n\n @property\n def description(self):\n return \"%s library\" % self.name\n\n @property\n def url(self):\n return \"https://git.grammatech.com/%s\" % self.rel_url\n\n @property\n def conan_channel(self):\n channel = \"local\"\n if \"CI_COMMIT_REF_NAME\" in os.environ:\n branch = os.environ[\"CI_COMMIT_REF_NAME\"]\n channel = branch_to_channel(branch)\n return channel\n\n @property\n def archived_channels(self):\n # Add to this list branch names to have conan packages for\n # branches archived in gitlab.\n archived_branches = [\"master\"]\n # Also, archive the 'stable' channel, where all stable versions\n # will be uploaded\n archived_channels = [\"stable\"]\n return archived_channels + list(\n map(branch_to_channel, archived_branches)\n )\n\n @property\n def conan_ref(self):\n channel = self.conan_channel\n return \"%s/%s\" % (self.rel_url.replace(\"/\", \"+\"), channel)\n\n @property\n def conan_recipe(self):\n return \"%s/%s@%s\" % (self.name, self.version, self.conan_ref)\n\n\nclass GtirbConan(Properties, ConanFile):\n boost_version = \"1.69.0\"\n protobuf_version = \"3.15.5\"\n requires = (\n \"boost/{0}\".format(boost_version),\n \"protobuf/{0}\".format(protobuf_version),\n )\n settings = \"os\", \"build_type\", \"compiler\", \"arch\"\n generators = \"cmake\"\n\n def configure(self):\n if (\n self.settings.compiler == \"gcc\"\n and self.settings.compiler.libcxx != \"libstdc++11\"\n ):\n raise ConanInvalidConfiguration(\n \"gtirb requires libstdc++11 ABI, update your conan profile\"\n )\n\n def build_requirements(self):\n if self.settings.os == \"Windows\":\n self.build_requires(\"ninja/1.10.2\")\n\n def build(self):\n if self.settings.os == \"Windows\":\n with tools.vcvars(\n self.settings, force=True, filter_known_paths=False\n ):\n self.build_cmake()\n else:\n self.build_cmake()\n\n def build_cmake(self):\n # Note: Only build the C++ API\n defs = {\n \"CMAKE_VERBOSE_MAKEFILE:BOOL\": \"ON\",\n \"ENABLE_CONAN:BOOL\": \"ON\",\n \"GTIRB_CXX_API:BOOL\": \"ON\",\n \"GTIRB_PY_API:BOOL\": \"OFF\",\n \"GTIRB_CL_API:BOOL\": \"OFF\",\n \"GTIRB_JAVA_API:BOOL\": \"OFF\",\n }\n disable_parallel_build = (\n int(os.environ.get(\"GTIRB_DISABLE_PARALLEL_BUILD\", \"0\")) != 0\n )\n if self.settings.os == \"Windows\":\n cmake = CMake(self, generator=\"Ninja\")\n defs.update(\n {\n k: os.environ.get(k)\n for k in [\"BOOST_ROOT\", \"CMAKE_PREFIX_PATH\", \"PYTHON\"]\n }\n )\n defs.update({\"Protobuf_USE_STATIC_LIBS\": \"ON\"})\n if disable_parallel_build:\n defs[\"GTIRB_MSVC_PARALLEL_COMPILE_JOBS\"] = \"1\"\n else:\n cmake = CMake(self, generator=None)\n defs.update({\"GTIRB_STRIP_DEBUG_SYMBOLS:BOOL\": \"ON\"})\n cmake.configure(\n source_folder=\".\",\n defs=defs,\n )\n if disable_parallel_build:\n cmake.parallel = False\n cmake.build()\n cmake.test(output_on_failure=True)\n cmake.install()\n # The patch_config_paths() function will change absolute paths in the\n # exported cmake config files to use the appropriate conan variables\n # instead.\n # It is an experimental feature of conan, however, so if you're having\n # trouble with paths in the cmake of the conan package, it could that\n # this function is no longer doing what we want.\n cmake.patch_config_paths()\n\n def package(self):\n pass\n\n def package_info(self):\n self.cpp_info.libs = [\"gtirb\"]\n\n def package_id(self):\n v = Version(str(self.settings.compiler.version))\n if self.settings.compiler == \"Visual Studio\" and v in [\"15\", \"16\"]:\n self.info.settings.compiler.version = \"Visual Studio 15 and 16\"\n" }, { "path": "cpack-config.cmake", "content": "# Global properties\nset(CMAKE_PROJECT_HOMEPAGE_URL https://github.com/GrammaTech/gtirb)\nset(CPACK_COMPONENTS_GROUPING ALL_COMPONENTS_IN_ONE)\n\nset(CPACK_DEB_COMPONENT_INSTALL ON)\n\n# Reusable lists of components\nset(LIB_COMPONENTS library license)\nset(DEV_COMPONENTS headers proto_library cmake_config cmake_target)\n\n# Debian packages\nif(\"${CPACK_GTIRB_PACKAGE}\" STREQUAL \"debian-lib\")\n set(CPACK_DEBIAN_PACKAGE_NAME \"libgtirb\")\n set(CPACK_DEBIAN_FILE_NAME DEB-DEFAULT)\n set(CPACK_COMPONENTS_ALL ${LIB_COMPONENTS})\n if(\"${CPACK_DEBIAN_PACKAGE_RELEASE}\" STREQUAL \"focal\")\n set(CPACK_DEBIAN_PACKAGE_DEPENDS\n \"libstdc++6, libc6, libgcc1, libprotobuf17\"\n )\n elseif(\"${CPACK_DEBIAN_PACKAGE_RELEASE}\" STREQUAL \"jammy\")\n set(CPACK_DEBIAN_PACKAGE_DEPENDS\n \"libstdc++6, libc6, libgcc-s1, libprotobuf23\"\n )\n elseif(\"${CPACK_DEBIAN_PACKAGE_RELEASE}\" STREQUAL \"noble\")\n set(CPACK_DEBIAN_PACKAGE_DEPENDS\n \"libstdc++6, libc6, libgcc-s1, libprotobuf32t64\"\n )\n else()\n message(\n SEND_ERROR \"Unknown / missing value for CPACK_DEBIAN_PACKAGE_RELEASE.\"\n )\n endif()\nelseif(\"${CPACK_GTIRB_PACKAGE}\" STREQUAL \"debian-dev\")\n set(CPACK_DEBIAN_PACKAGE_NAME \"libgtirb-dev\")\n set(CPACK_DEBIAN_FILE_NAME DEB-DEFAULT)\n set(CPACK_COMPONENTS_ALL ${DEV_COMPONENTS})\n set(CPACK_DEBIAN_PACKAGE_DEPENDS\n \"libgtirb (=${CPACK_GTIRB_VERSION}-${CPACK_DEBIAN_PACKAGE_RELEASE}), libboost-dev (>=1.68) | libboost1.68-dev, libprotobuf-dev (>=${CPACK_PROTOBUF_VERSION_LOWER_BOUND}~), libprotobuf-dev (<<${CPACK_PROTOBUF_VERSION_UPPER_BOUND})\"\n )\nelseif(\"${CPACK_GTIRB_PACKAGE}\" STREQUAL \"debian-debug\")\n set(CPACK_DEBIAN_PACKAGE_NAME \"libgtirb-dbg\")\n set(CPACK_DEBIAN_FILE_NAME DEB-DEFAULT)\n set(CPACK_COMPONENTS_ALL debug-file)\n set(CPACK_DEBIAN_PACKAGE_DEPENDS\n \"libgtirb (=${CPACK_GTIRB_VERSION}-${CPACK_DEBIAN_PACKAGE_RELEASE})\"\n )\nendif()\n" }, { "path": "doc/CFG-Edges.md", "content": "Advice on when to Place ICFG Edges\n==================================\n\nIt is not always straightforward when to construct ICFG edges. For\nexample, should there be an edge from a function's return to every\ncaller of that function? While GTIRB does not preclude or enforce any\nparticular ICFG connection strategy, we do propose the following\nsuggestions for how to handle many common situations.\n\n## Undefined/extern functions.\n\nHow to handle edges leaving call instructions to undefined or extern\nfunctions? In this case the function is not included in the module\nand thus is not a possible edge target in the ICFG.\n\n> ????\n\n## Fall through edges from call sites.\n\nSince we're working with an interprocedural CFG, we have edges from\ncall instructions to their targets. Do we also have edges from a call\ninstruction to the instruction immediately after it in memory?\n\n> Yes unless we know the callee does not return (e.g., exit).\n\n### Non-return functions.\n\nWhen generating code around non-return functions (like exit):\nsometimes compilers omit any following code if they know a call will\nnot return. For example in a situation like this (except in machine\ncode):\n\n```C\nvoid foo()\n{\n if (something) {\n bar_that_always_calls_exit();\n // stack cleanup\n return;\n }\n}\n```\n\nIn some cases, the compiler will know that\n`bar_that_always_calls_exit()` will never return. In some cases, the\ncompiler doesn't figure that out. In the former case, the compiler may\nomit the \"stack cleanup\" and \"return\" code. In the latter case, it\nwill not.\n\nIn some cases, your disassembly engine will know that\n`bar_that_always_calls_exit()` will never return. In some cases, your\ndisassembly engine doesn't figure that out. In the former case, you\ncan choose to omit the \"fall-through\" edge in your IR. In the latter\ncase, you won't, because you think the execution flow is possible.\n\nSo, if you get the combination: the compiler figured it out and you\ndid *not*. Then you will add the CFG edge from\n`bar_that_always_calls_exit()` to whatever follows. But whatever\nfollows will not necessarily be code in the function `foo()` or code\nat all really. It will be whatever random chunk of bytes the compiler\nhappened to plop down next.\n\nWe bring this up because it has bearing on your stance for adding\nedges from callsites to their follows. If you don't do that, you'll\nnever make this mistake.\n\nHowever, we suggest that in the balance, having the edges when your\ndisassembly is correct outweighs the presence of this error.\n\n\n## Edges from returns back to call sites.\n\nWhat about from a return instruction to corresponding call sites\n(plural) (or rather the instructions that follow them)?\n\n> Yes.\n\n## Edges from indirect calls to targets.\n\nIndirect calls: we won't know who the targets are always. And we won't\nknow to add edges from corresponding return instructions.\n\n> We put in edges (to and from) as we're able to identify them. We\n> don't conservatively put edges between every indirect call and every\n> function.\n\n## Tail calls.\n\nTail calls don't have return instructions or a place for a callee to\nreturn to.\n\n> Hook up the eventual return of a tail called function to the places\n> it could lead (i.e., non tail-call callers and callers of tail-call\n> callers).\n" }, { "path": "doc/CMakeLists.txt", "content": "add_custom_target(doc)\nfile(MAKE_DIRECTORY \"${CMAKE_CURRENT_BINARY_DIR}/html\")\n\nif(CXX_API)\n set(CPP_TAGFILE \"${CMAKE_CURRENT_BINARY_DIR}/CPP_DOXY.tag\")\n set(CPP_TAGFILE_RULE \"${CPP_TAGFILE}=cpp\")\n set(CPP_DOX_ENABLED \"CPP_ONLY\")\n set(CPP_API_VISIBLE \"yes\")\n add_subdirectory(cpp)\nelse()\n set(CPP_TAGFILE_RULE \"\")\n set(CPP_DOX_ENABLED \"\")\n set(CPP_API_VISIBLE \"no\")\nendif()\n\nif(PY_API)\n add_subdirectory(python)\n set(PY_DOX_ENABLED \"PY_ONLY\")\n set(PY_API_VISIBLE \"yes\")\nelse()\n set(PY_DOX_ENABLED \"\")\n set(PY_API_VISIBLE \"no\")\nendif()\n\nif(CL_API)\n add_subdirectory(cl)\n set(CL_DOX_ENABLED \"CL_ONLY\")\n set(CL_API_VISIBLE \"yes\")\nelse()\n set(CL_DOX_ENABLED \"\")\n set(CL_API_VISIBLE \"no\")\nendif()\n\nif(JAVA_API)\n add_subdirectory(java)\n set(JAVA_DOX_ENABLED \"JAVA_ONLY\")\n set(JAVA_API_VISIBLE \"yes\")\nelse()\n set(JAVA_DOX_ENABLED \"\")\n set(JAVA_API_VISIBLE \"no\")\nendif()\n\nadd_subdirectory(examples)\nadd_subdirectory(general)\n" }, { "path": "doc/binary-representation.md", "content": "Binary Representation with GTIRB\n================================\n\n- [Representing Binaries](#representing-binaries)\n - [Sections](#sections)\n - [Symbols](#symbols)\n - [Byte Intervals](#byte-intervals)\n - [Symbolic Expressions](#symbolic-expressions)\n\nGTIRB portably encodes binaries from a range of standard executable\nand linkable formats, such as\n[ELF](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format),\n[PE](https://en.wikipedia.org/wiki/Portable_Executable), and\n[Mach-O](https://en.wikipedia.org/wiki/Mach-O), allowing conversion to\nand from these formats to GTIRB. In ensure all information from the\noriginal binary is retained despite standard GTIRB data\nstructures--which are intended to be general across all binary\nrepresentations--being lossy for many aspects of particular\nrepresentation, encoders are encouraged to include all raw bytes of\nthe original file in the GTIRB encoding. In addition, GTIRB encodes\ninformation above and beyond what these formats store; it stores\ncontrol flow, symbolization (reference) information, and other\nanalysis results, with the goal of providing all essential information\nto support subsequent binary analysis and rewriting. Finally, GTIRB\nallows user-extensible data to be included in the form of AuxData\ntables which can easily reference other GTIRB elements--letting tools\ncommunicate with each other in a single standard in-file format.\n\n## Representing Binaries\n\nAlthough executable file formats differ in many ways, they typically\ntend to have a similar structure. The bytes of the image are divided\ninto sections, which contain the bytes consisting of the code and data\nalong with information about how to load and adjust them at run-time.\nTo facilitate linking with shared libraries, they have a symbol table,\nwhich specifies a list of names of entities this file provides or\nrequires. To facilitate relocation in memory these files often\ncontains a relocation table.\n\nGTIRB contains all this information in standard forms. In GTIRB, a\nsingle executable or library is encoded as a *module*. A GTIRB file\nmay have multiple modules, enclosed in a single *IR*. GTIRB encodes\nthe standard features of all binary formats in the following\nstructures:\n\n### Sections\n\nModules in GTIRB contain multiple *sections*. A section has a name\nreflecting any name given in the original file (e.g., `.text`), a set\nof properties, and a set of contents stored in\n[byte intervals](#byte-intervals).\n\n### Symbols\n\nRather than storing a symbol table as a section, GTIRB stores a set of\n*symbols* associated with every module. These symbols have a name, a\nset of properties, and a *referent*. A referent may be an integer,\nindicating that the symbol is a numeric constant or fixed address, or\na reference to a *block*. A block may be one of:\n\n| Block Kind | Description |\n|---------------|---------------------------------------------------------|\n| *code block* | a series of executable instructions |\n| *data block* | a series of data bytes |\n| *proxy block* | indicating that the symbol is defined in another module |\n\n### Byte Intervals\n\nThe bytes of a section are subdivided into chunks of bytes called\n*byte intervals*. This indirection layer serves two purposes:\n\n- Indicate what blocks can be moved independently of each other. It is\n guaranteed that you can shuffle around two byte intervals in a\n section, and doing so will preserve the program's semantics.\n- Support the generation of blocks with no original address. Byte\n intervals may have a fixed address, but they may also be unfixed,\n likely indicating that the byte interval was generated by a binary\n rewriting tool or is freely movable to any address.\n\nTwo byte intervals in the same section may not overlap in addresses\n(although sections can overlap with each other in some cases, such as\nin object code). Byte intervals contain code blocks or data blocks.\nThe blocks within a byte interval *can* overlap. Examples of\noverlapping blocks include:\n\n- Overlapping data blocks are common.\n - One data block may representing an array may overlap many data\n blocks representing elements of the array.\n - Compilers often overlap strings with shared suffixes. The data\n blocks representing these strings will similarly overlap.\n* Overlapping code blocks are rare, however particularly clever or\n malicious code blocks in variable-width ISAs may overlap when two\n different sequences of instructions serialize to machine-code bytes\n which share common subsequences.\n\nByte intervals also hold [symbolic expressions](#symbolic-expressions)\nwhich indicate symbolic contents of code or data blocks.\n\n### Symbolic Expressions\n\nTo encode relocations, GTIRB associates *symbolic expressions* with\nbyte-intervals. These specify that certain bytes in the binary refer\nto the address. This allows these bytes to be recalculated when the\nreferent is moved in the binary image.\n\nGTIRB does not specify exactly how symbolic expressions are\ntransformed into bytes. This depends on where the symbolic expression\nis located; inside a code block, it depends on what part of an\ninstruction it is of, while inside a data block, it depends on the\nsize of the data block.\n\nThere are currently three kinds of symbolic expressions:\n\n| Kind | Description |\n|-----------------|-------------------|\n| *SymAddrConst* | the address of the referent of a symbol, plus or minus a fixed offset |\n| *SymAddrAddr* | the difference between two symbols, divided by a scale and plus an offset |\n" }, { "path": "doc/cl/CMakeLists.txt", "content": "set(SDT_SCRIPT ${CMAKE_CURRENT_SOURCE_DIR}/write-documentation.lisp)\nset(README ${CMAKE_SOURCE_DIR}/cl/README.md)\nset(HTML_INDEX ${CMAKE_BINARY_DIR}/doc/html/cl/index.html)\n\nfile(MAKE_DIRECTORY \"${CMAKE_BINARY_DIR}/doc/html/cl\")\nfile(GLOB CL_SOURCES ${CMAKE_SOURCE_DIR}/cl/*.lisp ${CMAKE_SOURCE_DIR}/cl/*.asd)\n\nadd_custom_command(\n OUTPUT ${HTML_INDEX}\n DEPENDS ${SDT_SCRIPT} ${README} ${CL_SOURCES}\n COMMAND\n ${LISP} --noinform --dynamic-space-size 16384 --no-userinit --no-sysinit\n --disable-debugger --load ${QUICKLISP}/setup.lisp --eval\n \"(asdf:initialize-source-registry `(:source-registry (:tree \\\"${CMAKE_SOURCE_DIR}/cl\\\") :inherit-configuration))\"\n --script ${SDT_SCRIPT} gtirb ${README} ${HTML_INDEX}\n VERBATIM\n COMMENT \"Generating API documentation with SDT\"\n)\nadd_custom_target(sdt ALL DEPENDS ${HTML_INDEX})\nadd_dependencies(doc sdt)\n" }, { "path": "doc/cl/write-documentation.lisp", "content": ";; -*- lisp -*-\n;;\n;; Usage: write-documentation PKG ABSTRACT OUTPUT-HTML\n;; Write the automatically generated documentation for PKG to\n;; OUTPUT-HTML. The ABSTRACT should be a file in Markdown format to\n;; place at the top of the generated documentation.\n;;\n(load \"~/.sbclrc\" :if-does-not-exist nil)\n(ql:quickload :alexandria)\n(ql:quickload :simpler-documentation-template)\n(ql:quickload :markdown.cl)\n(unless (= (length sb-ext:*posix-argv*) 5)\n (format t \"Usage: write-documentation PKG ABSTRACT OUTPUT-HTML\"))\n(let ((package (alexandria:make-keyword\n (string-upcase (second sb-ext:*posix-argv*))))\n (abstract-path (third sb-ext:*posix-argv*))\n (output-path (fourth sb-ext:*posix-argv*)))\n (ql:quickload package)\n #+debug (format t \"Writing: ~S~%\" (list package abstract-path output-path))\n (simpler-documentation-template:create-template\n package\n :maybe-skip-methods-p t\n :target output-path\n :abstract-html (markdown.cl:parse\n (with-open-file (in abstract-path)\n (let* ((file-bytes (file-length in))\n (seq (make-string file-bytes))\n (file-chars (read-sequence seq in)))\n (subseq seq 0 file-chars))))))\n" }, { "path": "doc/cpp/CMakeLists.txt", "content": "# based on sample in https://majewsky.wordpress.com/2010/08/14/tip-of-the-day-\n# cmake-and-doxygen/ add a target to generate API documentation with Doxygen\n\ncmake_minimum_required(VERSION 3.3)\n\nfind_package(Doxygen)\nif(DOXYGEN_FOUND)\n\n set(ROOTDIR \"${CMAKE_CURRENT_SOURCE_DIR}/../..\")\n set(DOTDIR \"${CMAKE_CURRENT_SOURCE_DIR}/../dot\")\n\n set(BUILDFILES_IN ../preprocmd.py DoxygenLayout.xml)\n foreach(_inf ${BUILDFILES_IN})\n configure_file(\n ${CMAKE_CURRENT_SOURCE_DIR}/${_inf} ${CMAKE_CURRENT_BINARY_DIR}/${_inf}\n @ONLY\n )\n endforeach()\n\n # Handle version initialization\n file(READ \"${ROOTDIR}/version.txt\" ver)\n\n string(REGEX MATCH \"VERSION_MAJOR ([0-9]*)\" _ ${ver})\n set(GTIRB_MAJOR_VERSION ${CMAKE_MATCH_1})\n\n string(REGEX MATCH \"VERSION_MINOR ([0-9]*)\" _ ${ver})\n set(GTIRB_MINOR_VERSION ${CMAKE_MATCH_1})\n\n string(REGEX MATCH \"VERSION_PATCH ([0-9]*)\" _ ${ver})\n set(GTIRB_PATCH_VERSION ${CMAKE_MATCH_1})\n\n configure_file(\n \"${ROOTDIR}/include/gtirb/version.h.in\"\n \"${ROOTDIR}/include/gtirb/version.h\" @ONLY\n )\n\n configure_file(\n \"${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in\"\n \"${CMAKE_CURRENT_BINARY_DIR}/Doxyfile\" @ONLY\n )\n\n # adapted from https://gist.github.com/abravalheri/11214134\n\n macro(move_filename file_list newdir)\n foreach(src_file ${${file_list}})\n get_filename_component(src_file_name \"${src_file}\" NAME)\n list(REMOVE_ITEM ${file_list} \"${src_file}\")\n list(APPEND ${file_list} \"${newdir}/${src_file_name}\")\n endforeach()\n endmacro()\n\n # ----------------------------------------------------------------------\n # copy dot files into a subdir of the working directory\n # ----------------------------------------------------------------------\n file(GLOB DOTFILES_IN \"${DOTDIR}/*\")\n\n set(DOTFILES ${DOTFILES_IN})\n move_filename(DOTFILES ${CMAKE_CURRENT_BINARY_DIR})\n\n # message(\"DOTFILES = ${DOTFILES}\")\n\n add_custom_command(\n OUTPUT ${DOTFILES}\n WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}\n DEPENDS ${DOTFILES_IN}\n COMMAND mkdir -p dot\n COMMAND ${CMAKE_COMMAND} -E copy_directory ${DOTDIR} dot\n COMMENT \"copying dot dir\"\n VERBATIM\n )\n\n # ----------------------------------------------------------------------\n # copy md files into the working directory\n # ----------------------------------------------------------------------\n\n set(MDFILES_IN \"${CMAKE_CURRENT_SOURCE_DIR}/README.md\")\n\n set(MDFILES ${MDFILES_IN})\n move_filename(MDFILES ${CMAKE_CURRENT_BINARY_DIR})\n # message(\"MDFILES = ${MDFILES}\")\n\n gtirb_find_python()\n\n foreach(_inmd ${MDFILES_IN})\n get_filename_component(_outmd \"${_inmd}\" NAME)\n add_custom_command(\n OUTPUT ${_outmd}\n WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}\n DEPENDS ${_inmd}\n COMMAND ${CMAKE_COMMAND} -E copy ${_inmd} \"${_outmd}.in\"\n COMMAND ${PYTHON} ../preprocmd.py \"${_outmd}.in\" ${_outmd}\n COMMENT \"processing ${_outmd}\"\n VERBATIM\n )\n endforeach()\n\n # ----------------------------------------------------------------------\n # Main target\n # ----------------------------------------------------------------------\n\n add_custom_target(\n cpp_doxyout\n WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}\n DEPENDS ${DOTFILES}\n DEPENDS ${MDFILES}\n COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile\n COMMENT \"Generating C++ API documentation with Doxygen\"\n VERBATIM\n )\n\n add_dependencies(doc cpp_doxyout)\nendif(DOXYGEN_FOUND)\n" }, { "path": "doc/cpp/Doxyfile.in", "content": "# Doxyfile 1.8.11\n\n# This file describes the settings to be used by the documentation system\n# doxygen (www.doxygen.org) for a project.\n#\n# All text after a double hash (##) is considered a comment and is placed in\n# front of the TAG it is preceding.\n#\n# All text after a single hash (#) is considered a comment and will be ignored.\n# The format is:\n# TAG = value [value, ...]\n# For lists, items can also be appended using:\n# TAG += value [value, ...]\n# Values that contain spaces should be placed between quotes (\\\" \\\").\n\n#---------------------------------------------------------------------------\n# Project related configuration options\n#---------------------------------------------------------------------------\n\n# This tag specifies the encoding used for all characters in the config file\n# that follow. The default is UTF-8 which is also the encoding used for all text\n# before the first occurrence of this tag. Doxygen uses libiconv (or the iconv\n# built into libc) for the transcoding. See http://www.gnu.org/software/libiconv\n# for the list of possible encodings.\n# The default value is: UTF-8.\n\nDOXYFILE_ENCODING = UTF-8\n\n# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by\n# double-quotes, unless you are using Doxywizard) that should identify the\n# project for which the documentation is generated. This name is used in the\n# title of most generated pages and in a few other places.\n# The default value is: My Project.\n\nPROJECT_NAME = GTIRB\n\n# The PROJECT_NUMBER tag can be used to enter a project or revision number. This\n# could be handy for archiving the generated documentation or if some version\n# control system is used.\n\nPROJECT_NUMBER = v@GTIRB_MAJOR_VERSION@.@GTIRB_MINOR_VERSION@.@GTIRB_PATCH_VERSION@\n\n# Using the PROJECT_BRIEF tag one can provide an optional one line description\n# for a project that appears at the top of each page and should give viewer a\n# quick idea about the purpose of the project. Keep the description short.\n\nPROJECT_BRIEF = \"GrammaTech Intermediate Representation for Binaries: C++ API\"\n\n# With the PROJECT_LOGO tag one can specify a logo or an icon that is included\n# in the documentation. The maximum height of the logo should not exceed 55\n# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy\n# the logo to the output directory.\n\nPROJECT_LOGO =\n\n# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path\n# into which the generated documentation will be written. If a relative path is\n# entered, it will be relative to the location where doxygen was started. If\n# left blank the current directory will be used.\n\nOUTPUT_DIRECTORY = @CMAKE_BINARY_DIR@/doc\n\n# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-\n# directories (in 2 levels) under the output directory of each output format and\n# will distribute the generated files over these directories. Enabling this\n# option can be useful when feeding doxygen a huge amount of source files, where\n# putting all generated files in the same directory would otherwise causes\n# performance problems for the file system.\n# The default value is: NO.\n\nCREATE_SUBDIRS = NO\n\n# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII\n# characters to appear in the names of generated files. If set to NO, non-ASCII\n# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode\n# U+3044.\n# The default value is: NO.\n\nALLOW_UNICODE_NAMES = NO\n\n# The OUTPUT_LANGUAGE tag is used to specify the language in which all\n# documentation generated by doxygen is written. Doxygen will use this\n# information to generate all constant output in the proper language.\n# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese,\n# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States),\n# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian,\n# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages),\n# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian,\n# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian,\n# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish,\n# Ukrainian and Vietnamese.\n# The default value is: English.\n\nOUTPUT_LANGUAGE = English\n\n# If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member\n# descriptions after the members that are listed in the file and class\n# documentation (similar to Javadoc). Set to NO to disable this.\n# The default value is: YES.\n\nBRIEF_MEMBER_DESC = YES\n\n# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief\n# description of a member or function before the detailed description\n#\n# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the\n# brief descriptions will be completely suppressed.\n# The default value is: YES.\n\nREPEAT_BRIEF = YES\n\n# This tag implements a quasi-intelligent brief description abbreviator that is\n# used to form the text in various listings. Each string in this list, if found\n# as the leading text of the brief description, will be stripped from the text\n# and the result, after processing the whole list, is used as the annotated\n# text. Otherwise, the brief description is used as-is. If left blank, the\n# following values are used ($name is automatically replaced with the name of\n# the entity):The $name class, The $name widget, The $name file, is, provides,\n# specifies, contains, represents, a, an and the.\n\nABBREVIATE_BRIEF = \"The $name class\" \\\n \"The $name widget\" \\\n \"The $name file\" \\\n is \\\n provides \\\n specifies \\\n contains \\\n represents \\\n a \\\n an \\\n the\n\n# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then\n# doxygen will generate a detailed section even if there is only a brief\n# description.\n# The default value is: NO.\n\nALWAYS_DETAILED_SEC = NO\n\n# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all\n# inherited members of a class in the documentation of that class as if those\n# members were ordinary class members. Constructors, destructors and assignment\n# operators of the base classes will not be shown.\n# The default value is: NO.\n\nINLINE_INHERITED_MEMB = NO\n\n# If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path\n# before files name in the file list and in the header files. If set to NO the\n# shortest path that makes the file name unique will be used\n# The default value is: YES.\n\nFULL_PATH_NAMES = NO\n\n# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path.\n# Stripping is only done if one of the specified strings matches the left-hand\n# part of the path. The tag can be used to show relative paths in the file list.\n# If left blank the directory from which doxygen is run is used as the path to\n# strip.\n#\n# Note that you can specify absolute paths here, but also relative paths, which\n# will be relative from the directory where doxygen is started.\n# This tag requires that the tag FULL_PATH_NAMES is set to YES.\n\nSTRIP_FROM_PATH = .\n\n# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the\n# path mentioned in the documentation of a class, which tells the reader which\n# header file to include in order to use a class. If left blank only the name of\n# the header file containing the class definition is used. Otherwise one should\n# specify the list of include paths that are normally passed to the compiler\n# using the -I flag.\n\nSTRIP_FROM_INC_PATH =\n\n# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but\n# less readable) file names. This can be useful is your file systems doesn't\n# support long names like on DOS, Mac, or CD-ROM.\n# The default value is: NO.\n\nSHORT_NAMES = NO\n\n# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the\n# first line (until the first dot) of a Javadoc-style comment as the brief\n# description. If set to NO, the Javadoc-style will behave just like regular Qt-\n# style comments (thus requiring an explicit @brief command for a brief\n# description.)\n# The default value is: NO.\n\nJAVADOC_AUTOBRIEF = NO\n\n# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first\n# line (until the first dot) of a Qt-style comment as the brief description. If\n# set to NO, the Qt-style will behave just like regular Qt-style comments (thus\n# requiring an explicit \\brief command for a brief description.)\n# The default value is: NO.\n\nQT_AUTOBRIEF = NO\n\n# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a\n# multi-line C++ special comment block (i.e. a block of //! or /// comments) as\n# a brief description. This used to be the default behavior. The new default is\n# to treat a multi-line C++ comment block as a detailed description. Set this\n# tag to YES if you prefer the old behavior instead.\n#\n# Note that setting this tag to YES also means that rational rose comments are\n# not recognized any more.\n# The default value is: NO.\n\nMULTILINE_CPP_IS_BRIEF = NO\n\n# If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the\n# documentation from any documented member that it re-implements.\n# The default value is: YES.\n\nINHERIT_DOCS = YES\n\n# If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new\n# page for each member. If set to NO, the documentation of a member will be part\n# of the file/class/namespace that contains it.\n# The default value is: NO.\n\nSEPARATE_MEMBER_PAGES = NO\n\n# The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen\n# uses this value to replace tabs by spaces in code fragments.\n# Minimum value: 1, maximum value: 16, default value: 4.\n\nTAB_SIZE = 4\n\n# This tag can be used to specify a number of aliases that act as commands in\n# the documentation. An alias has the form:\n# name=value\n# For example adding\n# \"sideeffect=@par Side Effects:\\n\"\n# will allow you to put the command \\sideeffect (or @sideeffect) in the\n# documentation, which will result in a user-defined paragraph with heading\n# \"Side Effects:\". You can put \\n's in the value part of an alias to insert\n# newlines.\n\nALIASES =\n\n# This tag can be used to specify a number of word-keyword mappings (TCL only).\n# A mapping has the form \"name=value\". For example adding \"class=itcl::class\"\n# will allow you to use the command class in the itcl::class meaning.\n\nTCL_SUBST =\n\n# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources\n# only. Doxygen will then generate output that is more tailored for C. For\n# instance, some of the names that are used will be different. The list of all\n# members will be omitted, etc.\n# The default value is: NO.\n\nOPTIMIZE_OUTPUT_FOR_C = NO\n\n# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or\n# Python sources only. Doxygen will then generate output that is more tailored\n# for that language. For instance, namespaces will be presented as packages,\n# qualified scopes will look different, etc.\n# The default value is: NO.\n\nOPTIMIZE_OUTPUT_JAVA = NO\n\n# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran\n# sources. Doxygen will then generate output that is tailored for Fortran.\n# The default value is: NO.\n\nOPTIMIZE_FOR_FORTRAN = NO\n\n# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL\n# sources. Doxygen will then generate output that is tailored for VHDL.\n# The default value is: NO.\n\nOPTIMIZE_OUTPUT_VHDL = NO\n\n# Doxygen selects the parser to use depending on the extension of the files it\n# parses. With this tag you can assign which parser to use for a given\n# extension. Doxygen has a built-in mapping, but you can override or extend it\n# using this tag. The format is ext=language, where ext is a file extension, and\n# language is one of the parsers supported by doxygen: IDL, Java, Javascript,\n# C#, C, C++, D, PHP, Objective-C, Python, Fortran (fixed format Fortran:\n# FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran:\n# Fortran. In the later case the parser tries to guess whether the code is fixed\n# or free formatted code, this is the default for Fortran type files), VHDL. For\n# instance to make doxygen treat .inc files as Fortran files (default is PHP),\n# and .f files as C (default is Fortran), use: inc=Fortran f=C.\n#\n# Note: For files without extension you can use no_extension as a placeholder.\n#\n# Note that for custom extensions you also need to set FILE_PATTERNS otherwise\n# the files are not read by doxygen.\n\nEXTENSION_MAPPING =\n\n# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments\n# according to the Markdown format, which allows for more readable\n# documentation. See http://daringfireball.net/projects/markdown/ for details.\n# The output of markdown processing is further processed by doxygen, so you can\n# mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in\n# case of backward compatibilities issues.\n# The default value is: YES.\n\nMARKDOWN_SUPPORT = YES\n\n# When enabled doxygen tries to link words that correspond to documented\n# classes, or namespaces to their corresponding documentation. Such a link can\n# be prevented in individual cases by putting a % sign in front of the word or\n# globally by setting AUTOLINK_SUPPORT to NO.\n# The default value is: YES.\n\nAUTOLINK_SUPPORT = YES\n\n# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want\n# to include (a tag file for) the STL sources as input, then you should set this\n# tag to YES in order to let doxygen match functions declarations and\n# definitions whose arguments contain STL classes (e.g. func(std::string);\n# versus func(std::string) {}). This also make the inheritance and collaboration\n# diagrams that involve STL classes more complete and accurate.\n# The default value is: NO.\n\nBUILTIN_STL_SUPPORT = NO\n\n# If you use Microsoft's C++/CLI language, you should set this option to YES to\n# enable parsing support.\n# The default value is: NO.\n\nCPP_CLI_SUPPORT = NO\n\n# Set the SIP_SUPPORT tag to YES if your project consists of sip (see:\n# http://www.riverbankcomputing.co.uk/software/sip/intro) sources only. Doxygen\n# will parse them like normal C++ but will assume all classes use public instead\n# of private inheritance when no explicit protection keyword is present.\n# The default value is: NO.\n\nSIP_SUPPORT = NO\n\n# For Microsoft's IDL there are propget and propput attributes to indicate\n# getter and setter methods for a property. Setting this option to YES will make\n# doxygen to replace the get and set methods by a property in the documentation.\n# This will only work if the methods are indeed getting or setting a simple\n# type. If this is not the case, or you want to show the methods anyway, you\n# should set this option to NO.\n# The default value is: YES.\n\nIDL_PROPERTY_SUPPORT = YES\n\n# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC\n# tag is set to YES then doxygen will reuse the documentation of the first\n# member in the group (if any) for the other members of the group. By default\n# all members of a group must be documented explicitly.\n# The default value is: NO.\n\nDISTRIBUTE_GROUP_DOC = NO\n\n# If one adds a struct or class to a group and this option is enabled, then also\n# any nested class or struct is added to the same group. By default this option\n# is disabled and one has to add nested compounds explicitly via \\ingroup.\n# The default value is: NO.\n\nGROUP_NESTED_COMPOUNDS = NO\n\n# Set the SUBGROUPING tag to YES to allow class member groups of the same type\n# (for instance a group of public functions) to be put as a subgroup of that\n# type (e.g. under the Public Functions section). Set it to NO to prevent\n# subgrouping. Alternatively, this can be done per class using the\n# \\nosubgrouping command.\n# The default value is: YES.\n\nSUBGROUPING = YES\n\n# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions\n# are shown inside the group in which they are included (e.g. using \\ingroup)\n# instead of on a separate page (for HTML and Man pages) or section (for LaTeX\n# and RTF).\n#\n# Note that this feature does not work in combination with\n# SEPARATE_MEMBER_PAGES.\n# The default value is: NO.\n\nINLINE_GROUPED_CLASSES = NO\n\n# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions\n# with only public data fields or simple typedef fields will be shown inline in\n# the documentation of the scope in which they are defined (i.e. file,\n# namespace, or group documentation), provided this scope is documented. If set\n# to NO, structs, classes, and unions are shown on a separate page (for HTML and\n# Man pages) or section (for LaTeX and RTF).\n# The default value is: NO.\n\nINLINE_SIMPLE_STRUCTS = NO\n\n# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or\n# enum is documented as struct, union, or enum with the name of the typedef. So\n# typedef struct TypeS {} TypeT, will appear in the documentation as a struct\n# with name TypeT. When disabled the typedef will appear as a member of a file,\n# namespace, or class. And the struct will be named TypeS. This can typically be\n# useful for C code in case the coding convention dictates that all compound\n# types are typedef'ed and only the typedef is referenced, never the tag name.\n# The default value is: NO.\n\nTYPEDEF_HIDES_STRUCT = YES\n\n# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This\n# cache is used to resolve symbols given their name and scope. Since this can be\n# an expensive process and often the same symbol appears multiple times in the\n# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small\n# doxygen will become slower. If the cache is too large, memory is wasted. The\n# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range\n# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536\n# symbols. At the end of a run doxygen will report the cache usage and suggest\n# the optimal cache size from a speed point of view.\n# Minimum value: 0, maximum value: 9, default value: 0.\n\nLOOKUP_CACHE_SIZE = 0\n\n#---------------------------------------------------------------------------\n# Build related configuration options\n#---------------------------------------------------------------------------\n\n# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in\n# documentation are documented, even if no documentation was available. Private\n# class members and static file members will be hidden unless the\n# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES.\n# Note: This will also disable the warnings about undocumented members that are\n# normally produced when WARNINGS is set to YES.\n# The default value is: NO.\n\nEXTRACT_ALL = YES\n\n# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will\n# be included in the documentation.\n# The default value is: NO.\n\nEXTRACT_PRIVATE = NO\n\n# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal\n# scope will be included in the documentation.\n# The default value is: NO.\n\nEXTRACT_PACKAGE = NO\n\n# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be\n# included in the documentation.\n# The default value is: NO.\n\nEXTRACT_STATIC = NO\n\n# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined\n# locally in source files will be included in the documentation. If set to NO,\n# only classes defined in header files are included. Does not have any effect\n# for Java sources.\n# The default value is: YES.\n\nEXTRACT_LOCAL_CLASSES = YES\n\n# This flag is only useful for Objective-C code. If set to YES, local methods,\n# which are defined in the implementation section but not in the interface are\n# included in the documentation. If set to NO, only methods in the interface are\n# included.\n# The default value is: NO.\n\nEXTRACT_LOCAL_METHODS = NO\n\n# If this flag is set to YES, the members of anonymous namespaces will be\n# extracted and appear in the documentation as a namespace called\n# 'anonymous_namespace{file}', where file will be replaced with the base name of\n# the file that contains the anonymous namespace. By default anonymous namespace\n# are hidden.\n# The default value is: NO.\n\nEXTRACT_ANON_NSPACES = YES\n\n# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all\n# undocumented members inside documented classes or files. If set to NO these\n# members will be included in the various overviews, but no documentation\n# section is generated. This option has no effect if EXTRACT_ALL is enabled.\n# The default value is: NO.\n\nHIDE_UNDOC_MEMBERS = NO\n\n# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all\n# undocumented classes that are normally visible in the class hierarchy. If set\n# to NO, these classes will be included in the various overviews. This option\n# has no effect if EXTRACT_ALL is enabled.\n# The default value is: NO.\n\nHIDE_UNDOC_CLASSES = NO\n\n# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend\n# (class|struct|union) declarations. If set to NO, these declarations will be\n# included in the documentation.\n# The default value is: NO.\n\nHIDE_FRIEND_COMPOUNDS = NO\n\n# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any\n# documentation blocks found inside the body of a function. If set to NO, these\n# blocks will be appended to the function's detailed documentation block.\n# The default value is: NO.\n\nHIDE_IN_BODY_DOCS = NO\n\n# The INTERNAL_DOCS tag determines if documentation that is typed after a\n# \\internal command is included. If the tag is set to NO then the documentation\n# will be excluded. Set it to YES to include the internal documentation.\n# The default value is: NO.\n\nINTERNAL_DOCS = NO\n\n# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file\n# names in lower-case letters. If set to YES, upper-case letters are also\n# allowed. This is useful if you have classes or files whose names only differ\n# in case and if your file system supports case sensitive file names. Windows\n# and Mac users are advised to set this option to NO.\n# The default value is: system dependent.\n\nCASE_SENSE_NAMES = NO\n\n# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with\n# their full class and namespace scopes in the documentation. If set to YES, the\n# scope will be hidden.\n# The default value is: NO.\n\nHIDE_SCOPE_NAMES = NO\n\n# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will\n# append additional text to a page's title, such as Class Reference. If set to\n# YES the compound reference will be hidden.\n# The default value is: NO.\n\nHIDE_COMPOUND_REFERENCE= NO\n\n# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of\n# the files that are included by a file in the documentation of that file.\n# The default value is: YES.\n\nSHOW_INCLUDE_FILES = YES\n\n# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each\n# grouped member an include statement to the documentation, telling the reader\n# which file to include in order to use the member.\n# The default value is: NO.\n\nSHOW_GROUPED_MEMB_INC = YES\n\n# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include\n# files with double quotes in the documentation rather than with sharp brackets.\n# The default value is: NO.\n\nFORCE_LOCAL_INCLUDES = NO\n\n# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the\n# documentation for inline members.\n# The default value is: YES.\n\nINLINE_INFO = YES\n\n# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the\n# (detailed) documentation of file and class members alphabetically by member\n# name. If set to NO, the members will appear in declaration order.\n# The default value is: YES.\n\nSORT_MEMBER_DOCS = YES\n\n# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief\n# descriptions of file, namespace and class members alphabetically by member\n# name. If set to NO, the members will appear in declaration order. Note that\n# this will also influence the order of the classes in the class list.\n# The default value is: NO.\n\nSORT_BRIEF_DOCS = YES\n\n# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the\n# (brief and detailed) documentation of class members so that constructors and\n# destructors are listed first. If set to NO the constructors will appear in the\n# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS.\n# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief\n# member documentation.\n# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting\n# detailed member documentation.\n# The default value is: NO.\n\nSORT_MEMBERS_CTORS_1ST = YES\n\n# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy\n# of group names into alphabetical order. If set to NO the group names will\n# appear in their defined order.\n# The default value is: NO.\n\nSORT_GROUP_NAMES = YES\n\n# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by\n# fully-qualified names, including namespaces. If set to NO, the class list will\n# be sorted only by class name, not including the namespace part.\n# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES.\n# Note: This option applies only to the class list, not to the alphabetical\n# list.\n# The default value is: NO.\n\nSORT_BY_SCOPE_NAME = NO\n\n# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper\n# type resolution of all parameters of a function it will reject a match between\n# the prototype and the implementation of a member function even if there is\n# only one candidate or it is obvious which candidate to choose by doing a\n# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still\n# accept a match between prototype and implementation in such cases.\n# The default value is: NO.\n\nSTRICT_PROTO_MATCHING = NO\n\n# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo\n# list. This list is created by putting \\todo commands in the documentation.\n# The default value is: YES.\n\nGENERATE_TODOLIST = YES\n\n# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test\n# list. This list is created by putting \\test commands in the documentation.\n# The default value is: YES.\n\nGENERATE_TESTLIST = YES\n\n# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug\n# list. This list is created by putting \\bug commands in the documentation.\n# The default value is: YES.\n\nGENERATE_BUGLIST = YES\n\n# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO)\n# the deprecated list. This list is created by putting \\deprecated commands in\n# the documentation.\n# The default value is: YES.\n\nGENERATE_DEPRECATEDLIST= YES\n\n# The ENABLED_SECTIONS tag can be used to enable conditional documentation\n# sections, marked by \\if ... \\endif and \\cond \n# ... \\endcond blocks.\n\nENABLED_SECTIONS =\n\n# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the\n# initial value of a variable or macro / define can have for it to appear in the\n# documentation. If the initializer consists of more lines than specified here\n# it will be hidden. Use a value of 0 to hide initializers completely. The\n# appearance of the value of individual variables and macros / defines can be\n# controlled using \\showinitializer or \\hideinitializer command in the\n# documentation regardless of this setting.\n# Minimum value: 0, maximum value: 10000, default value: 30.\n\nMAX_INITIALIZER_LINES = 30\n\n# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at\n# the bottom of the documentation of classes and structs. If set to YES, the\n# list will mention the files that were used to generate the documentation.\n# The default value is: YES.\n\nSHOW_USED_FILES = YES\n\n# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This\n# will remove the Files entry from the Quick Index and from the Folder Tree View\n# (if specified).\n# The default value is: YES.\n\nSHOW_FILES = YES\n\n# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces\n# page. This will remove the Namespaces entry from the Quick Index and from the\n# Folder Tree View (if specified).\n# The default value is: YES.\n\nSHOW_NAMESPACES = YES\n\n# The FILE_VERSION_FILTER tag can be used to specify a program or script that\n# doxygen should invoke to get the current version for each file (typically from\n# the version control system). Doxygen will invoke the program by executing (via\n# popen()) the command command input-file, where command is the value of the\n# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided\n# by doxygen. Whatever the program writes to standard output is used as the file\n# version. For an example see the documentation.\n\nFILE_VERSION_FILTER =\n\n# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed\n# by doxygen. The layout file controls the global structure of the generated\n# output files in an output format independent way. To create the layout file\n# that represents doxygen's defaults, run doxygen with the -l option. You can\n# optionally specify a file name after the option, if omitted DoxygenLayout.xml\n# will be used as the name of the layout file.\n#\n# Note that if you run doxygen from a directory containing a file called\n# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE\n# tag is left empty.\n\nLAYOUT_FILE =\n\n# The CITE_BIB_FILES tag can be used to specify one or more bib files containing\n# the reference definitions. This must be a list of .bib files. The .bib\n# extension is automatically appended if omitted. This requires the bibtex tool\n# to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info.\n# For LaTeX the style of the bibliography can be controlled using\n# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the\n# search path. See also \\cite for info how to create references.\n\nCITE_BIB_FILES =\n\n#---------------------------------------------------------------------------\n# Configuration options related to warning and progress messages\n#---------------------------------------------------------------------------\n\n# The QUIET tag can be used to turn on/off the messages that are generated to\n# standard output by doxygen. If QUIET is set to YES this implies that the\n# messages are off.\n# The default value is: NO.\n\nQUIET = NO\n\n# The WARNINGS tag can be used to turn on/off the warning messages that are\n# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES\n# this implies that the warnings are on.\n#\n# Tip: Turn warnings on while writing the documentation.\n# The default value is: YES.\n\nWARNINGS = YES\n\n# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate\n# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag\n# will automatically be disabled.\n# The default value is: YES.\n\nWARN_IF_UNDOCUMENTED = YES\n\n# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for\n# potential errors in the documentation, such as not documenting some parameters\n# in a documented function, or documenting parameters that don't exist or using\n# markup commands wrongly.\n# The default value is: YES.\n\nWARN_IF_DOC_ERROR = YES\n\n# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that\n# are documented, but have no documentation for their parameters or return\n# value. If set to NO, doxygen will only warn about wrong or incomplete\n# parameter documentation, but not about the absence of documentation.\n# The default value is: NO.\n\nWARN_NO_PARAMDOC = NO\n\n# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when\n# a warning is encountered.\n# The default value is: NO.\n\nWARN_AS_ERROR = NO\n\n# The WARN_FORMAT tag determines the format of the warning messages that doxygen\n# can produce. The string should contain the $file, $line, and $text tags, which\n# will be replaced by the file and line number from which the warning originated\n# and the warning text. Optionally the format may contain $version, which will\n# be replaced by the version of the file (if it could be obtained via\n# FILE_VERSION_FILTER)\n# The default value is: $file:$line: $text.\n\nWARN_FORMAT = \"$file:$line: $text\"\n\n# The WARN_LOGFILE tag can be used to specify a file to which warning and error\n# messages should be written. If left blank the output is written to standard\n# error (stderr).\n\nWARN_LOGFILE = doxygen_warnings.txt\n\n#---------------------------------------------------------------------------\n# Configuration options related to the input files\n#---------------------------------------------------------------------------\n\n# The INPUT tag is used to specify the files and/or directories that contain\n# documented source files. You may enter file names like myfile.cpp or\n# directories like /usr/src/myproject. Separate the files or directories with\n# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING\n# Note: If this tag is empty the current directory is searched.\n\nINPUT = @CMAKE_CURRENT_SOURCE_DIR@/../../include @CMAKE_CURRENT_SOURCE_DIR@/../dot \\\n README.md\n\n# This tag can be used to specify the character encoding of the source files\n# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses\n# libiconv (or the iconv built into libc) for the transcoding. See the libiconv\n# documentation (see: http://www.gnu.org/software/libiconv) for the list of\n# possible encodings.\n# The default value is: UTF-8.\n\nINPUT_ENCODING = UTF-8\n\n# If the value of the INPUT tag contains directories, you can use the\n# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and\n# *.h) to filter out the source-files in the directories.\n#\n# Note that for custom extensions or not directly supported extensions you also\n# need to set EXTENSION_MAPPING for the extension otherwise the files are not\n# read by doxygen.\n#\n# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp,\n# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h,\n# *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc,\n# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f, *.for, *.tcl,\n# *.vhd, *.vhdl, *.ucf, *.qsf, *.as and *.js.\n\nFILE_PATTERNS = *.c \\\n *.cc \\\n *.cxx \\\n *.cpp \\\n *.c++ \\\n *.java \\\n *.ii \\\n *.ixx \\\n *.ipp \\\n *.i++ \\\n *.inl \\\n *.idl \\\n *.ddl \\\n *.odl \\\n *.h \\\n *.hh \\\n *.hxx \\\n *.hpp \\\n *.h++ \\\n *.cs \\\n *.d \\\n *.php \\\n *.php4 \\\n *.php5 \\\n *.phtml \\\n *.inc \\\n *.m \\\n *.markdown \\\n *.md \\\n *.mm \\\n *.dox \\\n *.py \\\n *.pyw \\\n *.f90 \\\n *.f \\\n *.for \\\n *.tcl \\\n *.vhd \\\n *.vhdl \\\n *.ucf \\\n *.qsf \\\n *.as \\\n *.js\n\n# The RECURSIVE tag can be used to specify whether or not subdirectories should\n# be searched for input files as well.\n# The default value is: NO.\n\nRECURSIVE = YES\n\n# The EXCLUDE tag can be used to specify files and/or directories that should be\n# excluded from the INPUT source files. This way you can easily exclude a\n# subdirectory from a directory tree whose root is specified with the INPUT tag.\n#\n# Note that relative paths are relative to the directory from which doxygen is\n# run.\n\nEXCLUDE =\n\n# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or\n# directories that are symbolic links (a Unix file system feature) are excluded\n# from the input.\n# The default value is: NO.\n\nEXCLUDE_SYMLINKS = NO\n\n# If the value of the INPUT tag contains directories, you can use the\n# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude\n# certain files from those directories.\n#\n# Note that the wildcards are matched against the file with absolute path, so to\n# exclude all test directories for example use the pattern */test/*\n\nEXCLUDE_PATTERNS = */include/proto/*.h\n\n# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names\n# (namespaces, classes, functions, etc.) that should be excluded from the\n# output. The symbol name can be a fully qualified name, a word, or if the\n# wildcard * is used, a substring. Examples: ANamespace, AClass,\n# AClass::ANamespace, ANamespace::*Test\n#\n# Note that the wildcards are matched against the file with absolute path, so to\n# exclude all test directories use the pattern */test/*\n\nEXCLUDE_SYMBOLS = proto\n\n# The EXAMPLE_PATH tag can be used to specify one or more files or directories\n# that contain example code fragments that are included (see the \\include\n# command).\n\nEXAMPLE_PATH =\n\n# If the value of the EXAMPLE_PATH tag contains directories, you can use the\n# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and\n# *.h) to filter out the source-files in the directories. If left blank all\n# files are included.\n\nEXAMPLE_PATTERNS = *\n\n# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be\n# searched for input files to be used with the \\include or \\dontinclude commands\n# irrespective of the value of the RECURSIVE tag.\n# The default value is: NO.\n\nEXAMPLE_RECURSIVE = NO\n\n# The IMAGE_PATH tag can be used to specify one or more files or directories\n# that contain images that are to be included in the documentation (see the\n# \\image command).\n\nIMAGE_PATH =\n\n# The INPUT_FILTER tag can be used to specify a program that doxygen should\n# invoke to filter for each input file. Doxygen will invoke the filter program\n# by executing (via popen()) the command:\n#\n# \n#\n# where is the value of the INPUT_FILTER tag, and is the\n# name of an input file. Doxygen will then use the output that the filter\n# program writes to standard output. If FILTER_PATTERNS is specified, this tag\n# will be ignored.\n#\n# Note that the filter must not add or remove lines; it is applied before the\n# code is scanned, but not when the output code is generated. If lines are added\n# or removed, the anchors will not be placed correctly.\n#\n# Note that for custom extensions or not directly supported extensions you also\n# need to set EXTENSION_MAPPING for the extension otherwise the files are not\n# properly processed by doxygen.\n\nINPUT_FILTER =\n\n# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern\n# basis. Doxygen will compare the file name with each pattern and apply the\n# filter if there is a match. The filters are a list of the form: pattern=filter\n# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how\n# filters are used. If the FILTER_PATTERNS tag is empty or if none of the\n# patterns match the file name, INPUT_FILTER is applied.\n#\n# Note that for custom extensions or not directly supported extensions you also\n# need to set EXTENSION_MAPPING for the extension otherwise the files are not\n# properly processed by doxygen.\n\nFILTER_PATTERNS =\n\n# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using\n# INPUT_FILTER) will also be used to filter the input files that are used for\n# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES).\n# The default value is: NO.\n\nFILTER_SOURCE_FILES = NO\n\n# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file\n# pattern. A pattern will override the setting for FILTER_PATTERN (if any) and\n# it is also possible to disable source filtering for a specific pattern using\n# *.ext= (so without naming a filter).\n# This tag requires that the tag FILTER_SOURCE_FILES is set to YES.\n\nFILTER_SOURCE_PATTERNS =\n\n# If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that\n# is part of the input, its contents will be placed on the main page\n# (index.html). This can be useful if you have a project on for instance GitHub\n# and want to reuse the introduction page also for the doxygen output.\n\nUSE_MDFILE_AS_MAINPAGE = README.md\n\n#---------------------------------------------------------------------------\n# Configuration options related to source browsing\n#---------------------------------------------------------------------------\n\n# If the SOURCE_BROWSER tag is set to YES then a list of source files will be\n# generated. Documented entities will be cross-referenced with these sources.\n#\n# Note: To get rid of all source code in the generated output, make sure that\n# also VERBATIM_HEADERS is set to NO.\n# The default value is: NO.\n\nSOURCE_BROWSER = NO\n\n# Setting the INLINE_SOURCES tag to YES will include the body of functions,\n# classes and enums directly into the documentation.\n# The default value is: NO.\n\nINLINE_SOURCES = NO\n\n# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any\n# special comment blocks from generated source code fragments. Normal C, C++ and\n# Fortran comments will always remain visible.\n# The default value is: YES.\n\nSTRIP_CODE_COMMENTS = YES\n\n# If the REFERENCED_BY_RELATION tag is set to YES then for each documented\n# function all documented functions referencing it will be listed.\n# The default value is: NO.\n\nREFERENCED_BY_RELATION = NO\n\n# If the REFERENCES_RELATION tag is set to YES then for each documented function\n# all documented entities called/used by that function will be listed.\n# The default value is: NO.\n\nREFERENCES_RELATION = NO\n\n# If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set\n# to YES then the hyperlinks from functions in REFERENCES_RELATION and\n# REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will\n# link to the documentation.\n# The default value is: YES.\n\nREFERENCES_LINK_SOURCE = YES\n\n# If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the\n# source code will show a tooltip with additional information such as prototype,\n# brief description and links to the definition and documentation. Since this\n# will make the HTML file larger and loading of large files a bit slower, you\n# can opt to disable this feature.\n# The default value is: YES.\n# This tag requires that the tag SOURCE_BROWSER is set to YES.\n\nSOURCE_TOOLTIPS = YES\n\n# If the USE_HTAGS tag is set to YES then the references to source code will\n# point to the HTML generated by the htags(1) tool instead of doxygen built-in\n# source browser. The htags tool is part of GNU's global source tagging system\n# (see http://www.gnu.org/software/global/global.html). You will need version\n# 4.8.6 or higher.\n#\n# To use it do the following:\n# - Install the latest version of global\n# - Enable SOURCE_BROWSER and USE_HTAGS in the config file\n# - Make sure the INPUT points to the root of the source tree\n# - Run doxygen as normal\n#\n# Doxygen will invoke htags (and that will in turn invoke gtags), so these\n# tools must be available from the command line (i.e. in the search path).\n#\n# The result: instead of the source browser generated by doxygen, the links to\n# source code will now point to the output of htags.\n# The default value is: NO.\n# This tag requires that the tag SOURCE_BROWSER is set to YES.\n\nUSE_HTAGS = NO\n\n# If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a\n# verbatim copy of the header file for each class for which an include is\n# specified. Set to NO to disable this.\n# See also: Section \\class.\n# The default value is: YES.\n\nVERBATIM_HEADERS = YES\n\n# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the\n# clang parser (see: http://clang.llvm.org/) for more accurate parsing at the\n# cost of reduced performance. This can be particularly helpful with template\n# rich C++ code for which doxygen's built-in parser lacks the necessary type\n# information.\n# Note: The availability of this option depends on whether or not doxygen was\n# generated with the -Duse-libclang=ON option for CMake.\n# The default value is: NO.\n\nCLANG_ASSISTED_PARSING = NO\n\n# If clang assisted parsing is enabled you can provide the compiler with command\n# line options that you would normally use when invoking the compiler. Note that\n# the include paths will already be set by doxygen for the files and directories\n# specified with INPUT and INCLUDE_PATH.\n# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES.\n\nCLANG_OPTIONS =\n\n#---------------------------------------------------------------------------\n# Configuration options related to the alphabetical class index\n#---------------------------------------------------------------------------\n\n# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all\n# compounds will be generated. Enable this if the project contains a lot of\n# classes, structs, unions or interfaces.\n# The default value is: YES.\n\nALPHABETICAL_INDEX = YES\n\n# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in\n# which the alphabetical index list will be split.\n# Minimum value: 1, maximum value: 20, default value: 5.\n# This tag requires that the tag ALPHABETICAL_INDEX is set to YES.\n\nCOLS_IN_ALPHA_INDEX = 5\n\n# In case all classes in a project start with a common prefix, all classes will\n# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag\n# can be used to specify a prefix (or a list of prefixes) that should be ignored\n# while generating the index headers.\n# This tag requires that the tag ALPHABETICAL_INDEX is set to YES.\n\nIGNORE_PREFIX =\n\n#---------------------------------------------------------------------------\n# Configuration options related to the HTML output\n#---------------------------------------------------------------------------\n\n# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output\n# The default value is: YES.\n\nGENERATE_HTML = YES\n\n# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a\n# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of\n# it.\n# The default directory is: html.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_OUTPUT = html/cpp\n\n# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each\n# generated HTML page (for example: .htm, .php, .asp).\n# The default value is: .html.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_FILE_EXTENSION = .html\n\n# The HTML_HEADER tag can be used to specify a user-defined HTML header file for\n# each generated HTML page. If the tag is left blank doxygen will generate a\n# standard header.\n#\n# To get valid HTML the header file that includes any scripts and style sheets\n# that doxygen needs, which is dependent on the configuration options used (e.g.\n# the setting GENERATE_TREEVIEW). It is highly recommended to start with a\n# default header using\n# doxygen -w html new_header.html new_footer.html new_stylesheet.css\n# YourConfigFile\n# and then modify the file new_header.html. See also section \"Doxygen usage\"\n# for information on how to generate the default header that doxygen normally\n# uses.\n# Note: The header is subject to change so you typically have to regenerate the\n# default header when upgrading to a newer version of doxygen. For a description\n# of the possible markers and block names see the documentation.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_HEADER =\n\n# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each\n# generated HTML page. If the tag is left blank doxygen will generate a standard\n# footer. See HTML_HEADER for more information on how to generate a default\n# footer and what special commands can be used inside the footer. See also\n# section \"Doxygen usage\" for information on how to generate the default footer\n# that doxygen normally uses.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_FOOTER =\n\n# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style\n# sheet that is used by each HTML page. It can be used to fine-tune the look of\n# the HTML output. If left blank doxygen will generate a default style sheet.\n# See also section \"Doxygen usage\" for information on how to generate the style\n# sheet that doxygen normally uses.\n# Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as\n# it is more robust and this tag (HTML_STYLESHEET) will in the future become\n# obsolete.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_STYLESHEET =\n\n# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined\n# cascading style sheets that are included after the standard style sheets\n# created by doxygen. Using this option one can overrule certain style aspects.\n# This is preferred over using HTML_STYLESHEET since it does not replace the\n# standard style sheet and is therefore more robust against future updates.\n# Doxygen will copy the style sheet files to the output directory.\n# Note: The order of the extra style sheet files is of importance (e.g. the last\n# style sheet in the list overrules the setting of the previous ones in the\n# list). For an example see the documentation.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_EXTRA_STYLESHEET =\n\n# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or\n# other source files which should be copied to the HTML output directory. Note\n# that these files will be copied to the base HTML output directory. Use the\n# $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these\n# files. In the HTML_STYLESHEET file, use the file name only. Also note that the\n# files will be copied as-is; there are no commands or markers available.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_EXTRA_FILES =\n\n# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen\n# will adjust the colors in the style sheet and background images according to\n# this color. Hue is specified as an angle on a colorwheel, see\n# http://en.wikipedia.org/wiki/Hue for more information. For instance the value\n# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300\n# purple, and 360 is red again.\n# Minimum value: 0, maximum value: 359, default value: 220.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_COLORSTYLE_HUE = 220\n\n# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors\n# in the HTML output. For a value of 0 the output will use grayscales only. A\n# value of 255 will produce the most vivid colors.\n# Minimum value: 0, maximum value: 255, default value: 100.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_COLORSTYLE_SAT = 100\n\n# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the\n# luminance component of the colors in the HTML output. Values below 100\n# gradually make the output lighter, whereas values above 100 make the output\n# darker. The value divided by 100 is the actual gamma applied, so 80 represents\n# a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not\n# change the gamma.\n# Minimum value: 40, maximum value: 240, default value: 80.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_COLORSTYLE_GAMMA = 80\n\n# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML\n# page will contain the date and time when the page was generated. Setting this\n# to YES can help to show when doxygen was last run and thus if the\n# documentation is up to date.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_TIMESTAMP = NO\n\n# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML\n# documentation will contain sections that can be hidden and shown after the\n# page has loaded.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_DYNAMIC_SECTIONS = NO\n\n# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries\n# shown in the various tree structured indices initially; the user can expand\n# and collapse entries dynamically later on. Doxygen will expand the tree to\n# such a level that at most the specified number of entries are visible (unless\n# a fully collapsed tree already exceeds this amount). So setting the number of\n# entries 1 will produce a full collapsed tree by default. 0 is a special value\n# representing an infinite number of entries and will result in a full expanded\n# tree by default.\n# Minimum value: 0, maximum value: 9999, default value: 100.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_INDEX_NUM_ENTRIES = 100\n\n# If the GENERATE_DOCSET tag is set to YES, additional index files will be\n# generated that can be used as input for Apple's Xcode 3 integrated development\n# environment (see: http://developer.apple.com/tools/xcode/), introduced with\n# OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a\n# Makefile in the HTML output directory. Running make will produce the docset in\n# that directory and running make install will install the docset in\n# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at\n# startup. See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html\n# for more information.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nGENERATE_DOCSET = NO\n\n# This tag determines the name of the docset feed. A documentation feed provides\n# an umbrella under which multiple documentation sets from a single provider\n# (such as a company or product suite) can be grouped.\n# The default value is: Doxygen generated docs.\n# This tag requires that the tag GENERATE_DOCSET is set to YES.\n\nDOCSET_FEEDNAME = \"Doxygen generated docs\"\n\n# This tag specifies a string that should uniquely identify the documentation\n# set bundle. This should be a reverse domain-name style string, e.g.\n# com.mycompany.MyDocSet. Doxygen will append .docset to the name.\n# The default value is: org.doxygen.Project.\n# This tag requires that the tag GENERATE_DOCSET is set to YES.\n\nDOCSET_BUNDLE_ID = org.doxygen.Project\n\n# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify\n# the documentation publisher. This should be a reverse domain-name style\n# string, e.g. com.mycompany.MyDocSet.documentation.\n# The default value is: org.doxygen.Publisher.\n# This tag requires that the tag GENERATE_DOCSET is set to YES.\n\nDOCSET_PUBLISHER_ID = org.doxygen.Publisher\n\n# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher.\n# The default value is: Publisher.\n# This tag requires that the tag GENERATE_DOCSET is set to YES.\n\nDOCSET_PUBLISHER_NAME = Publisher\n\n# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three\n# additional HTML index files: index.hhp, index.hhc, and index.hhk. The\n# index.hhp is a project file that can be read by Microsoft's HTML Help Workshop\n# (see: http://www.microsoft.com/en-us/download/details.aspx?id=21138) on\n# Windows.\n#\n# The HTML Help Workshop contains a compiler that can convert all HTML output\n# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML\n# files are now used as the Windows 98 help format, and will replace the old\n# Windows help format (.hlp) on all Windows platforms in the future. Compressed\n# HTML files also contain an index, a table of contents, and you can search for\n# words in the documentation. The HTML workshop also contains a viewer for\n# compressed HTML files.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nGENERATE_HTMLHELP = NO\n\n# The CHM_FILE tag can be used to specify the file name of the resulting .chm\n# file. You can add a path in front of the file if the result should not be\n# written to the html output directory.\n# This tag requires that the tag GENERATE_HTMLHELP is set to YES.\n\nCHM_FILE =\n\n# The HHC_LOCATION tag can be used to specify the location (absolute path\n# including file name) of the HTML help compiler (hhc.exe). If non-empty,\n# doxygen will try to run the HTML help compiler on the generated index.hhp.\n# The file has to be specified with full path.\n# This tag requires that the tag GENERATE_HTMLHELP is set to YES.\n\nHHC_LOCATION =\n\n# The GENERATE_CHI flag controls if a separate .chi index file is generated\n# (YES) or that it should be included in the master .chm file (NO).\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTMLHELP is set to YES.\n\nGENERATE_CHI = NO\n\n# The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc)\n# and project file content.\n# This tag requires that the tag GENERATE_HTMLHELP is set to YES.\n\nCHM_INDEX_ENCODING =\n\n# The BINARY_TOC flag controls whether a binary table of contents is generated\n# (YES) or a normal table of contents (NO) in the .chm file. Furthermore it\n# enables the Previous and Next buttons.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTMLHELP is set to YES.\n\nBINARY_TOC = NO\n\n# The TOC_EXPAND flag can be set to YES to add extra items for group members to\n# the table of contents of the HTML help documentation and to the tree view.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTMLHELP is set to YES.\n\nTOC_EXPAND = NO\n\n# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and\n# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that\n# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help\n# (.qch) of the generated HTML documentation.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nGENERATE_QHP = NO\n\n# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify\n# the file name of the resulting .qch file. The path specified is relative to\n# the HTML output folder.\n# This tag requires that the tag GENERATE_QHP is set to YES.\n\nQCH_FILE =\n\n# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help\n# Project output. For more information please see Qt Help Project / Namespace\n# (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace).\n# The default value is: org.doxygen.Project.\n# This tag requires that the tag GENERATE_QHP is set to YES.\n\nQHP_NAMESPACE = org.doxygen.Project\n\n# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt\n# Help Project output. For more information please see Qt Help Project / Virtual\n# Folders (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual-\n# folders).\n# The default value is: doc.\n# This tag requires that the tag GENERATE_QHP is set to YES.\n\nQHP_VIRTUAL_FOLDER = doc\n\n# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom\n# filter to add. For more information please see Qt Help Project / Custom\n# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-\n# filters).\n# This tag requires that the tag GENERATE_QHP is set to YES.\n\nQHP_CUST_FILTER_NAME =\n\n# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the\n# custom filter to add. For more information please see Qt Help Project / Custom\n# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-\n# filters).\n# This tag requires that the tag GENERATE_QHP is set to YES.\n\nQHP_CUST_FILTER_ATTRS =\n\n# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this\n# project's filter section matches. Qt Help Project / Filter Attributes (see:\n# http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes).\n# This tag requires that the tag GENERATE_QHP is set to YES.\n\nQHP_SECT_FILTER_ATTRS =\n\n# The QHG_LOCATION tag can be used to specify the location of Qt's\n# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the\n# generated .qhp file.\n# This tag requires that the tag GENERATE_QHP is set to YES.\n\nQHG_LOCATION =\n\n# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be\n# generated, together with the HTML files, they form an Eclipse help plugin. To\n# install this plugin and make it available under the help contents menu in\n# Eclipse, the contents of the directory containing the HTML and XML files needs\n# to be copied into the plugins directory of eclipse. The name of the directory\n# within the plugins directory should be the same as the ECLIPSE_DOC_ID value.\n# After copying Eclipse needs to be restarted before the help appears.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nGENERATE_ECLIPSEHELP = NO\n\n# A unique identifier for the Eclipse help plugin. When installing the plugin\n# the directory name containing the HTML and XML files should also have this\n# name. Each documentation set should have its own identifier.\n# The default value is: org.doxygen.Project.\n# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES.\n\nECLIPSE_DOC_ID = org.doxygen.Project\n\n# If you want full control over the layout of the generated HTML pages it might\n# be necessary to disable the index and replace it with your own. The\n# DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top\n# of each HTML page. A value of NO enables the index and the value YES disables\n# it. Since the tabs in the index contain the same information as the navigation\n# tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nDISABLE_INDEX = NO\n\n# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index\n# structure should be generated to display hierarchical information. If the tag\n# value is set to YES, a side panel will be generated containing a tree-like\n# index structure (just like the one that is generated for HTML Help). For this\n# to work a browser that supports JavaScript, DHTML, CSS and frames is required\n# (i.e. any modern browser). Windows users are probably better off using the\n# HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can\n# further fine-tune the look of the index. As an example, the default style\n# sheet generated by doxygen has an example that shows how to put an image at\n# the root of the tree instead of the PROJECT_NAME. Since the tree basically has\n# the same information as the tab index, you could consider setting\n# DISABLE_INDEX to YES when enabling this option.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nGENERATE_TREEVIEW = NO\n\n# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that\n# doxygen will group on one line in the generated HTML documentation.\n#\n# Note that a value of 0 will completely suppress the enum values from appearing\n# in the overview section.\n# Minimum value: 0, maximum value: 20, default value: 4.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nENUM_VALUES_PER_LINE = 4\n\n# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used\n# to set the initial width (in pixels) of the frame in which the tree is shown.\n# Minimum value: 0, maximum value: 1500, default value: 250.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nTREEVIEW_WIDTH = 250\n\n# If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to\n# external symbols imported via tag files in a separate window.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nEXT_LINKS_IN_WINDOW = NO\n\n# Use this tag to change the font size of LaTeX formulas included as images in\n# the HTML documentation. When you change the font size after a successful\n# doxygen run you need to manually remove any form_*.png images from the HTML\n# output directory to force them to be regenerated.\n# Minimum value: 8, maximum value: 50, default value: 10.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nFORMULA_FONTSIZE = 10\n\n# Use the FORMULA_TRANPARENT tag to determine whether or not the images\n# generated for formulas are transparent PNGs. Transparent PNGs are not\n# supported properly for IE 6.0, but are supported on all modern browsers.\n#\n# Note that when changing this option you need to delete any form_*.png files in\n# the HTML output directory before the changes have effect.\n# The default value is: YES.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nFORMULA_TRANSPARENT = YES\n\n# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see\n# http://www.mathjax.org) which uses client side Javascript for the rendering\n# instead of using pre-rendered bitmaps. Use this if you do not have LaTeX\n# installed or if you want to formulas look prettier in the HTML output. When\n# enabled you may also need to install MathJax separately and configure the path\n# to it using the MATHJAX_RELPATH option.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nUSE_MATHJAX = NO\n\n# When MathJax is enabled you can set the default output format to be used for\n# the MathJax output. See the MathJax site (see:\n# http://docs.mathjax.org/en/latest/output.html) for more details.\n# Possible values are: HTML-CSS (which is slower, but has the best\n# compatibility), NativeMML (i.e. MathML) and SVG.\n# The default value is: HTML-CSS.\n# This tag requires that the tag USE_MATHJAX is set to YES.\n\nMATHJAX_FORMAT = HTML-CSS\n\n# When MathJax is enabled you need to specify the location relative to the HTML\n# output directory using the MATHJAX_RELPATH option. The destination directory\n# should contain the MathJax.js script. For instance, if the mathjax directory\n# is located at the same level as the HTML output directory, then\n# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax\n# Content Delivery Network so you can quickly see the result without installing\n# MathJax. However, it is strongly recommended to install a local copy of\n# MathJax from http://www.mathjax.org before deployment.\n# The default value is: http://cdn.mathjax.org/mathjax/latest.\n# This tag requires that the tag USE_MATHJAX is set to YES.\n\nMATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest\n\n# The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax\n# extension names that should be enabled during MathJax rendering. For example\n# MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols\n# This tag requires that the tag USE_MATHJAX is set to YES.\n\nMATHJAX_EXTENSIONS =\n\n# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces\n# of code that will be used on startup of the MathJax code. See the MathJax site\n# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an\n# example see the documentation.\n# This tag requires that the tag USE_MATHJAX is set to YES.\n\nMATHJAX_CODEFILE =\n\n# When the SEARCHENGINE tag is enabled doxygen will generate a search box for\n# the HTML output. The underlying search engine uses javascript and DHTML and\n# should work on any modern browser. Note that when using HTML help\n# (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET)\n# there is already a search function so this one should typically be disabled.\n# For large projects the javascript based search engine can be slow, then\n# enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to\n# search using the keyboard; to jump to the search box use + S\n# (what the is depends on the OS and browser, but it is typically\n# , /