# CfgNet
CfgNet is a plugin-based framework for detecting and tracking dependencies among configuration options across the used technology stack of a software project.
Essentially, CfgNet represents configuration options of configuration artifacts as trees and connects them to build a configuration network, where links between the leaf nodes of a tree correspond to the dependencies between configuration options.
Our idea is to have a framework in which technology plugins analyze different configuration files (e.g., Dockerfiles or build scripts) and create nodes for configuration options with their user-defined values.
Linker plugins then connect the nodes in case a dependency exists using a specific linker heuristic.
We envision that CfgNet is used within a Git hook (e.g., pre-commit hook) to prevent dependency conflicts during the development and maintenance of software systems.
That is, whenever changes are made, CfgNet can check the changes before the actual commit gets pushed to the repository and reports a warning if it has detected possible dependency conflicts.
This way, developer can check the changes again and even use the information that CfgNet provides to fix the dependency conflicts.
## Installation
CfgNet is a package on PyPI. You can install it with the following command:
pip install cfgnet
You can also build it locally with [poetry](https://python-poetry.org/).
Please refer to the documentation of poetry for further details.
## Basic Usage
CfgNet provides a method-based command line interface with the commands `init`, `validate`, `export`, `analyze`, and `extract`.
Each method requires the `project_root` as option that points towards the root directory of the project on which you want to apply the CfgNet.
To initialize a reference configuration network, use the `init` command.
cfgnet init <project_root>
To detect dependency conflicts against the initialized reference network, you need to call
the `validate` command. Detected dependency conflicts will be displayed on screen.
cfgnet validate <project_root>
To export the reference network for visualization, use the `export` command.
The `export` command additionally requires a `output` and `format` option.
While the former specifies the name of the output file the latter defines which format the configuration network should be converted to.
Available formats are `json` and `dot`.
By default, the export includes only linked value nodes.
To export all nodes from the configuration network, you have te set the option `include-unlinked`.
cfgnet export --output=<name> --format=<format> <project_root>
cfgnet export --output=<name> --format=<format> --include-unlinked <project_root>
To visualize the reference network immediately without exporting the format, use the `export` command with the `-visualize-dot` option.
The visualization of the configuration network is stored in `.cfgnet/export` using the `png` format by default.
However, the format can be changed to either `pdf` or `png` using the format option.
By default, the network visualization includes only linked value nodes.
To visualize the entire configuration network including value nodes that are not linked to other nodes, you have to set the option `include-unlinked`.
cfgnet export --output=<name> --visualize-dot <project_root>
cfgnet export --output=<name> --format=<format> --visualize-dot <project_root>
cfgnet export --output=<name> --format=<format> --include-unlinked --visualize-dot <project_root>
The `analyze` command is used for analyzing the commit history of software systems in an automated manner.
When the analysis is finished, all detected configuration conflicts will be stored in `.cfgnet/analysis`.
cfgnet analyze <project_root>
To extract the key-value pairs of all configuration artifacts within a software project, use the `extract` command. The `extract` command additionally requires an `output` options, which specifies the directory where the key-value pairs are stored using the JSON format.
cfgnet extract <project_root> --output=<output>
The commands `init` and `analyze` can be further configured with the following options:
(1) --enable-static-blacklist
(2) --enable-internal-conflicts
(3) --enable-all-conflicts
(4) --config-files=<absolute_file_path>
These options enable (1) blacklisted values, which are taken into account when creating links, (2) the detection of conflicts within the same configuration artifact, (3) the detection of all conflict types, and (4) parsing of specific configuration files (e.g., configuration files of the operating machine that are not in the git repository of the software project), respectively. The option `--config-files` can be specified multiple times. The `config-file` option can also be used to configure the `extract` command.
For a documentation of further options run
cfgnet --help
## Documentation
You can build the documentation with
make docs
The HTML version of the documentation will be in `docs/_build/html`.
## Contributing
To contribute to this project feel free to create pull requests.
Please read our [guidelines and instructions for development][development] first.
[releases]: https://github.com/AI-4-SE/CfgNet/releases
[development]: docs/development.rst
Raw data
{
"_id": null,
"home_page": "https://github.com/digital-bauhaus/CfgNet",
"name": "CfgNet",
"maintainer": "Sebastian Simon",
"docs_url": null,
"requires_python": "<3.12,>=3.8",
"maintainer_email": "ssimon@informatik.uni-leipzig.de",
"keywords": "configuration",
"author": "Sebastian Simon",
"author_email": "ssimon@informatik.uni-leipzig.de",
"download_url": "https://files.pythonhosted.org/packages/ee/d0/da79f7e11fc3a5c6465d4cca17f943dc783557bb661cbb11b3c07e630ba8/cfgnet-1.0.4.tar.gz",
"platform": null,
"description": "\n\n\n# CfgNet\n\nCfgNet is a plugin-based framework for detecting and tracking dependencies among configuration options across the used technology stack of a software project.\nEssentially, CfgNet represents configuration options of configuration artifacts as trees and connects them to build a configuration network, where links between the leaf nodes of a tree correspond to the dependencies between configuration options.\nOur idea is to have a framework in which technology plugins analyze different configuration files (e.g., Dockerfiles or build scripts) and create nodes for configuration options with their user-defined values.\nLinker plugins then connect the nodes in case a dependency exists using a specific linker heuristic.\n\nWe envision that CfgNet is used within a Git hook (e.g., pre-commit hook) to prevent dependency conflicts during the development and maintenance of software systems. \nThat is, whenever changes are made, CfgNet can check the changes before the actual commit gets pushed to the repository and reports a warning if it has detected possible dependency conflicts. \nThis way, developer can check the changes again and even use the information that CfgNet provides to fix the dependency conflicts.\n\n## Installation\n\nCfgNet is a package on PyPI. You can install it with the following command:\n\n pip install cfgnet\n\nYou can also build it locally with [poetry](https://python-poetry.org/).\nPlease refer to the documentation of poetry for further details.\n\n## Basic Usage\n\nCfgNet provides a method-based command line interface with the commands `init`, `validate`, `export`, `analyze`, and `extract`.\nEach method requires the `project_root` as option that points towards the root directory of the project on which you want to apply the CfgNet.\n\nTo initialize a reference configuration network, use the `init` command.\n\n cfgnet init <project_root>\n\n\nTo detect dependency conflicts against the initialized reference network, you need to call\nthe `validate` command. Detected dependency conflicts will be displayed on screen.\n\n cfgnet validate <project_root>\n\n\nTo export the reference network for visualization, use the `export` command.\nThe `export` command additionally requires a `output` and `format` option.\nWhile the former specifies the name of the output file the latter defines which format the configuration network should be converted to.\nAvailable formats are `json` and `dot`.\nBy default, the export includes only linked value nodes.\nTo export all nodes from the configuration network, you have te set the option `include-unlinked`. \n\n cfgnet export --output=<name> --format=<format> <project_root>\n cfgnet export --output=<name> --format=<format> --include-unlinked <project_root>\n\nTo visualize the reference network immediately without exporting the format, use the `export` command with the `-visualize-dot` option. \nThe visualization of the configuration network is stored in `.cfgnet/export` using the `png` format by default.\nHowever, the format can be changed to either `pdf` or `png` using the format option.\nBy default, the network visualization includes only linked value nodes.\nTo visualize the entire configuration network including value nodes that are not linked to other nodes, you have to set the option `include-unlinked`. \n\n cfgnet export --output=<name> --visualize-dot <project_root>\n cfgnet export --output=<name> --format=<format> --visualize-dot <project_root>\n cfgnet export --output=<name> --format=<format> --include-unlinked --visualize-dot <project_root>\n\nThe `analyze` command is used for analyzing the commit history of software systems in an automated manner.\nWhen the analysis is finished, all detected configuration conflicts will be stored in `.cfgnet/analysis`.\n\n cfgnet analyze <project_root>\n\nTo extract the key-value pairs of all configuration artifacts within a software project, use the `extract` command. The `extract` command additionally requires an `output` options, which specifies the directory where the key-value pairs are stored using the JSON format. \n\n cfgnet extract <project_root> --output=<output>\n\nThe commands `init` and `analyze` can be further configured with the following options:\n \n (1) --enable-static-blacklist\n (2) --enable-internal-conflicts\n (3) --enable-all-conflicts\n (4) --config-files=<absolute_file_path>\n\nThese options enable (1) blacklisted values, which are taken into account when creating links, (2) the detection of conflicts within the same configuration artifact, (3) the detection of all conflict types, and (4) parsing of specific configuration files (e.g., configuration files of the operating machine that are not in the git repository of the software project), respectively. The option `--config-files` can be specified multiple times. The `config-file` option can also be used to configure the `extract` command.\n\nFor a documentation of further options run\n\n cfgnet --help\n\n## Documentation\n\nYou can build the documentation with\n\n make docs\n\nThe HTML version of the documentation will be in `docs/_build/html`.\n\n## Contributing\n\nTo contribute to this project feel free to create pull requests.\nPlease read our [guidelines and instructions for development][development] first.\n\n[releases]: https://github.com/AI-4-SE/CfgNet/releases\n[development]: docs/development.rst\n",
"bugtrack_url": null,
"license": "GPL-3.0+",
"summary": "A Framework for Tracking Configuration Dependencies Across a Software Project",
"version": "1.0.4",
"project_urls": {
"Homepage": "https://github.com/digital-bauhaus/CfgNet"
},
"split_keywords": [
"configuration"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2eadc2ba576238162a354a5354f5c74ddbd29bea871767664f56ada5a5d6196d",
"md5": "9111e31162b399495f5cc2694e977ec7",
"sha256": "83d1b70e58b9b00089fdc337b8dfe489453e5de6f5c4358d8471f45115de32da"
},
"downloads": -1,
"filename": "cfgnet-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9111e31162b399495f5cc2694e977ec7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.8",
"size": 109240,
"upload_time": "2024-11-15T15:36:40",
"upload_time_iso_8601": "2024-11-15T15:36:40.069587Z",
"url": "https://files.pythonhosted.org/packages/2e/ad/c2ba576238162a354a5354f5c74ddbd29bea871767664f56ada5a5d6196d/cfgnet-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "eed0da79f7e11fc3a5c6465d4cca17f943dc783557bb661cbb11b3c07e630ba8",
"md5": "c1c9758bde3ac72e8c990eaa791cc30e",
"sha256": "fdb8e8880758a20d0d2a13600f9cf0524f5aa844a3d9a99e2967022488206a31"
},
"downloads": -1,
"filename": "cfgnet-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "c1c9758bde3ac72e8c990eaa791cc30e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.8",
"size": 60241,
"upload_time": "2024-11-15T15:36:41",
"upload_time_iso_8601": "2024-11-15T15:36:41.384917Z",
"url": "https://files.pythonhosted.org/packages/ee/d0/da79f7e11fc3a5c6465d4cca17f943dc783557bb661cbb11b3c07e630ba8/cfgnet-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-15 15:36:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "digital-bauhaus",
"github_project": "CfgNet",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cfgnet"
}
JSON
