{"id":28717109,"url":"https://github.com/micro-ros/benchmarking_shadow-builder","last_synced_at":"2025-06-15T03:13:38.416Z","repository":{"id":48682449,"uuid":"259624350","full_name":"micro-ROS/benchmarking_shadow-builder","owner":"micro-ROS","description":"Repositiory containing the shadow-builder benchmarking tool","archived":false,"fork":false,"pushed_at":"2022-01-21T08:55:24.000Z","size":132,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2023-03-01T22:52:24.440Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/micro-ROS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-28T11:59:30.000Z","updated_at":"2022-04-17T01:53:54.000Z","dependencies_parsed_at":"2022-08-31T23:21:37.103Z","dependency_job_id":null,"html_url":"https://github.com/micro-ROS/benchmarking_shadow-builder","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"purl":"pkg:github/micro-ROS/benchmarking_shadow-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-ROS%2Fbenchmarking_shadow-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-ROS%2Fbenchmarking_shadow-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-ROS%2Fbenchmarking_shadow-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-ROS%2Fbenchmarking_shadow-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/micro-ROS","download_url":"https://codeload.github.com/micro-ROS/benchmarking_shadow-builder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-ROS%2Fbenchmarking_shadow-builder/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259914930,"owners_count":22931333,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-15T03:13:12.924Z","updated_at":"2025-06-15T03:13:38.395Z","avatar_url":"https://github.com/micro-ROS.png","language":"C++","readme":"Shadow Builder and Trace Framework Abstraction\n============================================\n\nThe Trace Framework Abstraction is a module that will be part of the shadow\nbuilder. This module is in charge of abstracting the underlying tracing tool\nused to benchmark.  The tool is still a stiLl a work in progress \n(everything is perfectible). So over time new features and bugs resolving will\nbe pushed.\n\n# Table of Contents\n\n1. [Concepts](#concepts)\n2. [Architecture](#architecture)\n3. [Getting started](#getting-started)\n4. [Tested platforms](#tested_platform)\n5.  [Common errors and bugs](#common-errors-and-bugs)\n\n# Concepts\n\nThere are some information to know before jumping into the shadow builder. The\narchitecture section provides a glampse of the tool's guts. But before starting, we need some\nterminology to speak the same language.\n\n## Terminology\n\n### Tags\n A tag is a comment that is use by the shadow-builder. A comment formatted\nas follow:\n\n * /\\*\\* Benchmarking::ModuleGroup::Function \\*/ : without any parameters,\n * /\\*\\* Benchmarking::ModuleGroup::Function(param0,...,paramN) \\*/ : with\n   paramaters\n\nis considered a _shadow-builder comment_ also known as a **Tag**.\n\n### TFA: Trace Framework Abstraction  \n\nThis is a Framework provided to aid deloveloper to create various plugin.\n\n### Plugins\n\nPlugins are library files that are providing replacement for a **Tag**.\n\n### Parser\n\nThe element (front-end) in charge of looking for comment within a string. If\nthis string comment is **Tag** it's dispatched.\n\n# Architecture\n\nThe Shadow-Builder is made of 4 core components that are:\n\n * **The parser element**: Which is just a backend tool that indicates the TFA\n   module that a **Tag** was found in the source code. It's also in charge of\n   writing some piece of code. Currently, the llvm and clang are used to parse\n   and adapt the code. The use of clang libtooling is documented more in details\n   on the official webpage: [https://releases.llvm.org/10.0.0/tools/clang/docs/index.html](https://releases.llvm.org/10.0.0/tools/clang/docs/index.html) .\n\n * **The TFA module**: This software is in charge of manipulating the different \n   plugins and dispatch the **Tags** found by the the parser\n   element. It will perform a first filtering to make sure this comment is \n   formated correctly. In addition it also sanitises the commentaries (also\n   called tags). The TFA module undersanding is quite straight forware but more details are provided\n   within the [tfa_core/README.md](tfa_core/README.md) .\n\n * **The TFA plugins**: These are element that answer to a TFA module dispatch\n   when a commentary matches the commentaries. The plugins are basically a\n   shared library file that will be opened on startup. Some more details how to\n   use and write them here: [tfa-plugins/README.md](tfa-plugins/README.md) .\n\n * **Shadow Builder**: The umbrella core module that is in charge of\n   orchestrating the modules aforementionned. More about it here \n   [shadow-builder/README.md](shadow-builder/README.md) . \n\n## Tree\n\nBelow the tree view of the important folders, files and their descriptions.\n\nshadow_builder\\\n\t├── common  \t\t--\u003e Toolbox source files \\\n\t├── examples\t\t--\u003e Examples of instrumented code \\\n\t├── ext\t\t\t--\u003e External dl and libraries (do not pollute your machine and no need for docker) \\\n\t├── prepare_build.sh    --\u003e Script fetching and installing the dependencies \\\n\t├── res\t\t\t--\u003e Configuration files folder \\\n\t├── shadow-builder\t--\u003e Shadowbuilder source files \\\n\t├── tfa_core\t\t--\u003e TFA's source files, \\\n\t└── tfa-plugins\t\t--\u003e TFA plugin's folder.\n\n# Getting started\n\n## Dependencies\n\nFirst of all, in order to start compiling the shadow-builder it is needed to\nretrieve a list of dependencies. \n\n### Under Ubuntu 18.04:\n\n``` shell\nsudo apt install git libzmq3-dev binutils libssl-dev python3-distutils python3\nsudo snap install cmake --classic # To get a more recent version of cmake.\n```\n\nIn order to build clang and LLVM, gcc 9 is needed. Under the official ppa, this\nis not possible to find it. Therefore, we will need to install from a test ppa:\n\n``` shell\nsudo add-apt-repository ppa:ubuntu-toolchain-r/test # Accept the key by pressing enter\nsudo apt update\nsudo apt install gcc-9 g++-9 g++-9-multilib\n```\n\nThen once this is done, as you might already have a gcc on your machine, the \nupdate-alternative should be used to have different version of gcc. If the\nalternative for gcc is available and set up on your machine, you can direclty skip the\ncommand block below.\n\n``` shell\nsudo update-alternatives --remove-all gcc\nsudo update-alternatives --remove-all cc\nsudo update-alternatives --remove-all g++\nsudo update-alternatives --remove-all c++\n\nsudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-xxx 10 # This is your gcc compiler\nsudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-9 20\n\nsudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-xxx 10 # This is your g++ compiler\nsudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-9 20\n\nsudo update-alternatives --install /usr/bin/cc cc /usr/bin/gcc 30\nsudo update-alternatives --set cc /usr/bin/gcc\n\nsudo update-alternatives --install /usr/bin/c++ c++ /usr/bin/g++ 30\nsudo update-alternatives --set c++ /usr/bin/g++\n\nsudo update-alternatives --install /usr/bin/c++ c++ /usr/bin/g++ 30\nsudo update-alternatives --set c++ /usr/bin/g++\n``` \n\nThen select the gcc9 and g++9 as following:\n\n``` shell\nsudo update-alternatives --config gcc\nThere are 2 choices for the alternative gcc (providing /usr/bin/gcc).\n\n  Selection    Path            Priority   Status\n------------------------------------------------------------\n* 0            /usr/bin/gcc-9   20        auto mode\n  1            /usr/bin/gcc-7   10        manual mode\n  2            /usr/bin/gcc-9   20        manual mode\n\nPress \u003center\u003e to keep the current choice[*], or type selection number: 2\n```\n\nAnd repeat those steps for:\n * c++ --\u003e selecting /usr/bin/g++\n * cc --\u003e selecting /usr/bin/gcc\n * gcc --\u003e selecting /usr/bin/gcc-9\n * g++ --\u003e selecting /usr/bin/g++-9\n\n\nIt is possible to check if the right version of gcc and g++ in the command line:\n\n``` shell\ngcc -v\ng++ -v\ncc -v\nc++ -v\n```\n\n\nIf some depencies were to be missing, please feel free to add them into this\ndocument and then initiate a pull request.\n\n## Compilation \n\nBefore starting, some internal dependencies must be retrieved. To do so, the\nscript at the root of folder should be called as follow:\n\n``` shell\n./prepare_build.sh # retrieves/compiles and installs dependencies\n```\n\nOnce this step is done, you can delete the ext/dl subdirectory. This will save you a lot\nof space\n\n**This might take some time, go grab yourself a coffee**\n\n\nThen once all dependencies are built, the shadow-builder is ready to be\ncompiled:\n\n``` shell\nmkdir -p build; cd build\ncmake ..\nmake -j4\n```\n\n## First run: using the example/example_stupid_main\n\nTo run the the shadow buidler against the examples (located ina examples/example_stupid_main),\nthe following steps to perform are:\n\n```shell\ncd build # previously created during the compilation step.\n./shadow-program -s ../res/sb-res/bcf.xml -t ../res/tfa-res/tfa.xmlb\n```\n\nThis command will create an instrumented code that will be generated in the\nfolder /tmp/output/test_DATE. \n\nOnce in the folder, the following commands will compile and execute the code:\n\n``` shell\ncd /tmp/output/test_DATE/\nmkdir -p build; cd build\ncmake .. ; make\n./simple_stupid_example \n```\n\nThe output of this command should be:\n\n``` shell\nMonitor var i: 0\nMonitor var i: 4294967295\nExe time: 8 sec : 758 ms : 534352 ns\n```\n\nTo understand what is going, it is recommanded to go through all configurations\nfile explaination and readmes, the examples code and its readme. \n\nFor more details, refering to all readmes are a good start. The code is\ndocumentated as well and can provide additional information about what is going\non at a very low level.\n\n## Configuration files\n\nThe shadow-builder is using XML configuration files to locate the TFA pluging folder \n**currently only one folder can be provided**. By default the plugin folder will\nbe located in the folder \u003csrc_root\u003e/tfa-plugins/\n\nMore information regarding the different attributes and node fo the XML\nconfiguraition can be find here: [res/README.md](res/README.md) .\n\n## Plugins\n\nPlugins are the \"Responder\" to _Tags_ that are found in the code. This _Tags_\nare used to tell the shadow-buidler and more specifically its plugins that a\nsome benchmarking request are made in the code. \n\nThe response is up to the implementation in the plugin. For more details, please\nhave a look here [tfa-plugins/README.md](tfa-plugins/README.md) .\n\n\n## Unit tests\n\nUnit tests are available in the folder \u003cmodule\u003e/tests/xxx_\\\u003cxx\\\u003e.cpp\nEach test shall be added in the CMakeFile.txt in the module you are testing.\n\nIn addition the option -DENABLE_TESTS=ON shall be passed to the cmake to\nactivate tests creation.\n\nCurently a few are test are performed. In the future, more unit test will\nbe added.\n\n# Tested Platforms\n\nThe shadow-builder was successfully compiled with ubuntu 18.04 LTS with the following\nconfiguration:\n\n * 2 Core / 4 Threads Intel Processor\n * 4GB DDR4 RAM / 8 GB of swapping memory,\n * 60 GB of disk space.\n\n# Common errors and bugs\n\n## Not enough Disk space\n\nCompilations of LLVM and clang are producing a lot of object files et so on.\nDuring the preparation, it is needed around 36GB of disk space.\n\n## Not enough RAM during LLVM/clang compilation\n\nThis error might occur during the execution of the script prepare_build.sh\n\nUnfortunately the LLVM/clang compilation is quite greedy when it comes to resources needed\nto compile it.\n\nOne error arise with low RAM. Currently the only way to solve  would be to increase\nthe swap size as explained here [https://askubuntu.com/questions/927854/how-do-i-increase-the-size-of-swapfile-without-removing-it-in-the-terminal](https://askubuntu.com/questions/927854/how-do-i-increase-the-size-of-swapfile-without-removing-it-in-the-terminal)\n\n# LICENSE\n\nShadow Builder tool suite (which include the TFA and Shadow-Builder) are to be open-sourced under the Apache-2.0 license. See the\n[LICENSE](./LICENSE) file for details.\n\nFor a list of other open-source components included in Shadow Builder tool suite (which include the TFA and Shadow-Builder), see\nthe file [3rd-party-licenses.md](./3rd-party-licenses.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicro-ros%2Fbenchmarking_shadow-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicro-ros%2Fbenchmarking_shadow-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicro-ros%2Fbenchmarking_shadow-builder/lists"}