{"id":18560768,"url":"https://github.com/eepp/vlttng","last_synced_at":"2025-04-10T02:31:11.246Z","repository":{"id":51356327,"uuid":"59193437","full_name":"eepp/vlttng","owner":"eepp","description":"Create LTTng virtual environments","archived":false,"fork":false,"pushed_at":"2025-04-03T18:12:59.000Z","size":339,"stargazers_count":9,"open_issues_count":2,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-03T18:27:00.163Z","etag":null,"topics":["lttng","sandbox","virtualenv"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eepp.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-19T09:38:00.000Z","updated_at":"2025-04-03T18:13:02.000Z","dependencies_parsed_at":"2024-02-22T02:23:10.146Z","dependency_job_id":"dfe2f169-26cd-4ae6-880a-dd60202d304a","html_url":"https://github.com/eepp/vlttng","commit_stats":{"total_commits":177,"total_committers":4,"mean_commits":44.25,"dds":0.07344632768361581,"last_synced_commit":"27c775db01ba13f27cb77bd5e6eca022c0db42bc"},"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eepp%2Fvlttng","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eepp%2Fvlttng/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eepp%2Fvlttng/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eepp%2Fvlttng/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eepp","download_url":"https://codeload.github.com/eepp/vlttng/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248144186,"owners_count":21054881,"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":["lttng","sandbox","virtualenv"],"created_at":"2024-11-06T22:04:33.762Z","updated_at":"2025-04-10T02:31:11.237Z","avatar_url":"https://github.com/eepp.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"// Render with Asciidoctor\n\n= vlttng\nPhilippe Proulx \u003chttps://eepp.ca/\u003e\n:toc:\n\nimage:https://img.shields.io/pypi/v/vlttng.svg?label=Latest%20version[link=\"https://pypi.python.org/pypi/vlttng\"]\n\n**_vlttng_** is a tool which creates a virtual environment (a sandbox)\nto run specific versions of the http://lttng.org/[LTTng] packages.\n\nThe https://babeltrace.org/[Babeltrace]{nbsp}1 and{nbsp}2,\nhttps://liburcu.org/[Userspace RCU],\nhttps://github.com/lttng/lttng-analyses[LTTng analyses],\nhttps://github.com/lttng/lttng-scope[LTTng Scope], and\nhttp://tracecompass.org/[Trace Compass] projects are also supported, as\nwell as some of the project dependencies.\n\n== Install vlttng\n\nTo install vlttng on the system:\n\n* Use `pip3`:\n+\n--\n----\n$ sudo pip3 install --upgrade vlttng\n----\n--\n\nTo install vlttng in your home directory:\n\n* Use `pip3`:\n+\n--\n----\n$ pip3 install --user --upgrade vlttng\n----\n--\n+\nThe commands are installed in `~/.local/bin`.\n\nTwo new commands are available: `vlttng` and `vlttng-quick`.\n\n== Quickstart\n\nThe easiest way to get started with vlttng is to use its `vlttng-quick`\ncommand. This command interactively asks you a few questions to create a\nbasic `vlttng` command line that you can use later or immediately.\n\n== How does vlttng work?\n\nThe `vlttng` command does the following:\n\n. Reads one or more _profiles_ that you give on the command line to know\n  which packages to fetch and build.\n\n. Fetches and extracts the requested packages.\n+\nvlttng supports Git with a specific branch/tag/commit as well as\nHTTP/FTP tarball sources. The Git clone URL can point to a local Git\nrepository using the `file://` protocol.\n\n. Builds one package at a time, setting some environment variables and\n  configure options so that the dependencies of the packages are\n  contained within the virtual environment.\n\n. Creates an `activate` script which you can _source_ from your\n  Bash/Zsh prompt to \"`enter`\" the virtual environment.\n+\nThis script sets a few environment variables, like `PATH`,\n`LD_LIBRARY_PATH`, and `PYTHONPATH`, to achieve this. By default, it\nalso prepends the name of the virtual environment directory to your\nshell prompt for you to know which virtual environment is active.\n+\nWhen you source the `activate` script, if the LTTng-modules project is\npart of the effective profile, `vlttng` removes the currently loaded\nLTTng kernel modules and sets the `MODPROBE_OPTIONS` environment\nvariable so that the LTTng session daemon loads the virtual environment\nmodules.\n\nExample:\n\n----\n$ vlttng -p lttng-stable-2.11 -p babeltrace2-master -p babeltrace2-python \\\n         -p lttng-tools-no-lttng-relayd -p urcu-stable-0.10 virt\n----\n\nHere, we're using five profiles to create a virtual environment in the\n`virt` directory. Source the generated `activate` script to enter the\nvirtual environment:\n\n----\n$ . ./virt/activate\n----\n\nYour prompt starts with `[virt]` after this (the name of the virtual\nenvironment directory).\n\n\"`Exit`\" the virtual environment with the `vlttng-deactivate` command.\nYour prompt will return to its previous value.\n\n== Write and use profiles\n\nA vlttng profile is a layer of configuration. You can use multiple\nprofiles to create an _effective profile_.\n\nThe project ships with more than 1000 default profiles. Use\n`vlttng --list-default-profiles` to list their names.\n\nProfiles are written in YAML. Here's an example:\n\n[source,yaml]\n----\nbuild-env:\n  CFLAGS: -O0 -g3\nvirt-env:\n  ENABLE_FEATURE: '1'\n  SOME_PATH: /path/to/omg\nprojects:\n  lttng-tools:\n    source: 'git://git.lttng.org/lttng-tools.git'\n    checkout: stable-2.11\n    build-env:\n      CC: clang\n      CFLAGS: ''\n  lttng-ust:\n    source: 'http://lttng.org/files/lttng-ust/lttng-ust-2.11.0.tar.bz2'\n    configure: --enable-python-agent\n  lttng-modules:\n    source: 'git://git.lttng.org/lttng-modules.git'\n    checkout: stable-2.11\n  urcu:\n    source: 'git://git.liburcu.org/userspace-rcu.git'\n----\n\nA few things to note here:\n\n* The root `build-env` property defines the base build environment\n  variables. They are set when building the projects. `vlttng` also\n  passes exported shell variables to the executed programs, so you can\n  do:\n+\n----\n$ CC=clang CFLAGS='-O0 -g3' vlttng ...\n----\n\n* The root `virt-env` property defines the virtual environment\n  variables, which are set when you activate the virtual environment.\n  Exported shell variables when you run `vlttng` are _not_ set when\n  you activate the resulting virtual environment.\n* The available project names, as of this version, are:\n** `babeltrace2`\n** `babeltrace`\n** `elfutils`\n** `glib`\n** `libxml2`\n** `lttng-analyses`\n** `lttng-modules`\n** `lttng-scope`\n** `lttng-tools`\n** `lttng-ust`\n** `popt`\n** `tracecompass`\n** `urcu`\n* The `build-env` property of a specific project defines environment\n  variables to be used only during the build stage of this project. A\n  project-specific build-time environment variable overrides a base\n  build-time environment variable sharing its name.\n* When the `source` property contains a Git URL, or when the `checkout`\n  property is set, the `checkout` property indicates which branch, tag,\n  or commit to check out. When it's not specified, `vlttng` checks out\n  the `master` branch.\n* The `configure` property specifies the options to pass to the\n  `configure` script of a given project. `vlttng` takes care of some\n  options itself, like `--prefix` and `--without-lttng-ust`, to create a\n  working virtual environment.\n\nYou can save the profile above to a file, for example `my-profile.yml`,\nand then you can create a virtual environment out of it:\n\n----\n$ vlttng -p my-profile.yml virt\n----\n\nWhen you give multiple profiles to `vlttng`, the first profile is\n\"`patched`\" with the second, which is then patched with the third, and\nso on, as such:\n\n* Nonexistent properties are created.\n* Existing properties are replaced recursively.\n* The `configure` properties are _joined_.\n\nFor example, let's add the following profile (call it `more.yaml`) to\nthe example above:\n\n[source,yaml]\n----\nbuild-env:\n  CFLAGS: -O0\n  SOMEVAR: ok\nprojects:\n  lttng-tools:\n    source: 'https://github.com/lttng/lttng-tools.git'\n  lttng-ust:\n    configure: --enable-java-agent-jul\n----\n\nWith this command:\n\n----\n$ vlttng -p my-profile.yml -p more.yaml virt\n----\n\nthe effective profile is:\n\n[source,yaml]\n----\nbuild-env:\n  CFLAGS: -O0\n  SOMEVAR: ok\nprojects:\n  lttng-tools:\n    source: 'https://github.com/lttng/lttng-tools.git'\n    checkout: stable-2.11\n    build-env:\n      CC: clang\n      CFLAGS: ''\n  lttng-ust:\n    source: 'http://lttng.org/files/lttng-ust/lttng-ust-2.11.0.tar.bz2'\n    configure: --enable-python-agent --enable-java-agent-jul\n  lttng-modules:\n    source: 'git://git.lttng.org/lttng-modules.git'\n    checkout: stable-2.11\n  urcu:\n    source: 'git://git.liburcu.org/userspace-rcu.git'\n----\n\n[[override]]\n== Override a profile property\n\nReplace, append to, and remove effective profile properties (after\n`vlttng` has merged all the profiles given with the `--profile` option\nas an effective profile) with the `--override` (`-o`) option.\n\nThe three override operations are:\n\nReplace a property:: {empty}\n+\n----\nPATH=REPLACEMENT\n----\n\nAppend to a property:: {empty}\n+\n----\nPATH+=APPEND\n----\n\nRemove a property:: {empty}\n+\n----\n!PATH\n----\n\n`PATH` is the path to the property, from the root of the profile, using\na dot-separated list of keys to find recursively.\n\nExample:\n\n----\n-o projects.lttng-tools.configure+=--disable-bin-lttng-relayd \\\n-o '!projects.lttng-ust.checkout' \\\n-o build-env.CC=clang\n----\n\nIn replace and append modes, `vlttng` creates the property if it does\nnot exist. This allows you to create projects on the command line:\n\n----\n-o projects.lttng-tools.source=https://github.com/lttng/lttng-tools.git \\\n-o projects.lttng-tools.checkout=v2.11.0 \\\n-o projects.lttng-tools.configure='--disable-bin-lttng --disable-man-pages'\n----\n\n`vlttng` applies the overrides in command line order.\n\n== Ignore a project\n\nIgnore specific projects that exist in the effective profile with the\n`--ignore-project` (`-i`) option:\n\n----\n$ vlttng -p lttng-stable-2.11 -p urcu-master -i lttng-ust virt\n----\n\nThis is the equivalent of removing the project's property with an\n\u003c\u003coverride,override\u003e\u003e:\n\n----\n$ vlttng -p lttng-stable-2.11 -p urcu-master -o '!projects.lttng-ust' virt\n----\n\n== Make the output verbose\n\nBy default, `vlttng` hides the standard output and error of the commands\nit runs. In this mode, `vlttng` prints all the commands to run and the\nexported environment variables along with comments, so that you can\n\"`replay`\" the entire output as is to create the same virtual\nenvironment (except for the `activate` script which would not be\ngenerated).\n\nYou can use the `--verbose` (`-v`) option to also print the standard\noutput and error of all the executed commands, and the effective profile\nused to create the virtual environment.\n\n== Define the number of make jobs\n\n`vlttng` passes its `--jobs` (`-j`) option as is to `make`.\n\nThe default value of the `--jobs` option is the number of active CPUs on\nyour system.\n\n== `activate` script options\n\nWhen you source the `activate` script, use the following environment\nvariables to alter its behaviour:\n\n`VLTTNG_NO_RMMOD`::\n    Set to `1` to disable the unloading of the currently loaded LTTng\n    kernel modules.\n\n`VLTTNG_NO_PROMPT`::\n    Set to `1` to keep your current shell prompt after the activation.\n\n== Use `sudo`\n\nIf you use `sudo` when the virtual environment is activated, make sure\nto use its `--preserve-env` (`-E`) option so that the virtual\nenvironment is preserved when it executes the command.\n\nAlso use the `env` command, setting the `PATH` variable to its current\nvalue because otherwise `sudo` won't find the command.\n\nFor example, to start a root LTTng session daemon which loads the LTTng\nkernel modules installed in the virtual environment:\n\n----\n$ sudo --preserve-env env PATH=\"$PATH\" lttng-sessiond --daemonize\n----\n\n== Trace a Java application\n\nWhen the LTTng-UST project is built with a Java agent, the activation\nof the virtual environment sets the `VLTTNG_CLASSPATH` environment\nvariable to a Java class path to use when you compile and run\nJava applications.\n\nExample:\n\n----\n$ javac -cp $VLTTNG_CLASSPATH MyClass.java\n$ java -cp $VLTTNG_CLASSPATH:. MyClass\n----\n\n== Use the virtual environment's Python packages\n\nIf the LTTng-UST Python agent is built and installed in the virtual\nenvironment, there's nothing special to do to trace a Python\napplication: the `PYTHONPATH` environment variable contains the path to\nthe LTTng-UST Python agent package in the virtual environment. You can\nimport the `lttngust` package as usual.\n\nAs such, you can import the `babeltrace` and `bt2` Python{nbsp}3\npackages directly.\n\n== Update a project with a Git source\n\n`vlttng` generates the following scripts in the virtual environment's\nroot directory (`_NAME_` is the project name):\n\n`conf-_NAME_.bash`::\n    Runs the configuration step of the project.\n\n`build-_NAME_.bash`::\n    Runs the build step of the project.\n\n`install-_NAME_.bash`::\n    Runs the install step of the project.\n\n`update-_NAME_.bash` (only with a Git source)::\n    Fetches the project's configured Git remote, checks out the latest\n    version of the configured branch, and runs `conf-_NAME_.bash`,\n    `build-_NAME_.bash`, and `install-_NAME_.bash`.\n\nIMPORTANT: Use those scripts with caution. For a stable branch, they\n_should_ work most of the time. For the `master` branch, some required\nimplicit configuration and build command lines might be missing from the\nscripts when you use the update script.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feepp%2Fvlttng","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feepp%2Fvlttng","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feepp%2Fvlttng/lists"}