{"id":19079280,"url":"https://github.com/covesa/ifex","last_synced_at":"2025-04-30T05:24:16.288Z","repository":{"id":37745283,"uuid":"279667718","full_name":"COVESA/ifex","owner":"COVESA","description":"The Interface Exchange Framework.   Tools for processing interface/API descriptions in different formats, including the IFEX core format.  Some example files are at: https://github.com/COVESA/vehicle_service_catalog.","archived":false,"fork":false,"pushed_at":"2025-04-16T13:44:52.000Z","size":498,"stargazers_count":16,"open_issues_count":39,"forks_count":17,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-16T20:27:35.722Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/COVESA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-07-14T18:49:58.000Z","updated_at":"2025-04-16T13:44:31.000Z","dependencies_parsed_at":"2023-12-12T18:45:50.142Z","dependency_job_id":"28c03afc-ce24-41c3-aad3-abf7a07be45b","html_url":"https://github.com/COVESA/ifex","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/COVESA%2Fifex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/COVESA%2Fifex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/COVESA%2Fifex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/COVESA%2Fifex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/COVESA","download_url":"https://codeload.github.com/COVESA/ifex/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251646471,"owners_count":21620930,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T02:14:05.704Z","updated_at":"2025-04-30T05:24:16.264Z","avatar_url":"https://github.com/COVESA.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Interface Exchange framework (IFEX)\n\n\u003cimg src=\"docs/images/IFEX-Logo-updated-turquoise%201.svg\" alt=\"IFEX Logo Turquoise SVG\" width=\"300\" height=\"118\"\u003e\n\nThis repository includes:\n\n1. Specifications and documentation\n2. Programs and tools\n\n...for the the *Interface Exchange framework (IFEX)*.\n\nIFEX is a general interface description and transformation technology to\nintegrate/unify/translate different IDLs, and provide tools and methods to\nfacilitate system integration using popular IPC/RPC protocols, and a variety of\ndeployment technologies.\n\nIn addition, IFEX defines a Interface Model (and its associated YAML syntax =\nIDL), which can be _optionally_ used as a one-and-all source format for\ninterface definitions.  The flexible core model together with the strong\n_Composable Layers_ design makes it a strong candidate for being the most\ncapable interface description approach available. However, using the\ntranslation tools does not in itself require accepting the IFEX \"IDL\" as the\nunifying format.\n\n## Documentation\n\nPlease refer to the [documentation](https://covesa.github.io/ifex) for more information.\n\n## IFEX software tools\n\nSome of the programs implement the tools for reading/writing/translating\ninterface descriptions and code-generation.  Other programs generate the IFEX\ninterface model/language-specification and other documentation.\n\nThe implementations are primarily written in python and using some preferred\ntechnologies, such as the [Jinja2 templating language](https://jinja.palletsprojects.com) \n([(alt.  link)](https://jinja2docs.readthedocs.io/en/stable/)).\n\n## Project Structure\n\n```\n├── docs\n│   ├── MD-formatted documents, templates for generation, and static content.\n│   ├── README.md =\u003e when viewing docs directory in GitHub, the README is rendered\n├── helpers\n│   ├── Integrations to associated ecosystems and tools\n│   ├── How-tos or scripts to run code-generation on output results\n│   ├── Example:  sd-bus-c++ generator tools\n├── input_filters\n│   ├── Separate dirs for each supported input IDL\n│   ├── Implementation of common code for parsing/reading each format\n│   ├──    ... but not including the AST definitions (see models/)\n│   ├──    ... therefore, dirs are not guaranteed to include any code\n           ... if it is self contained under the respective transformation implementation\n│   ├──    ... however, some common code for a language may find its place here\n├── output_filters\n│   ├── Separate dirs for each supported interface description model\n│   ├── Implementation of converters from ANY (AST) to text IDL\n│   ├──    ... in other words \"print out this AST\" type of function\n│   ├── JSON-schema generation\n│   ├── Jinja templates exist here\n├── models\n│   ├── Separate dirs for each supported interface description model\n│   ├── The internal models (a.k.a. AST definition) for IFEX and other languages\n├── packaging\n│   ├── Helper files for packaging the project in various ways\n│   ├── docker - Docker deployment, for testing and/or end-user use\n│   └── entrypoints - \n│       ├── Short script wrappers defining entry-points for python tools\n│       ├──    ... defines the executable commands created when installing the package\n├── requirements.txt, pyproject.toml, tox.ini. - Python dependencies expressed in different ways\n├── scripts\n│   ├── Helper scripts primarily used for development, not end-user scripts\n├── tests\n│   ├── Unit test definitions, and input data\n└── transformers\n│   ├── Separate dirs for each supported interface description model\n│   ├── Generic rule-based \"transformation engine\" implementation, that may be used by multiple tools\n│   ├── Implementation of specific transformers, if not covered by input/output filters\n\n```\n\n## Getting started\n\n### Prerequisites\n* Python \u003e=3.10 installed (exact version might vary - the best\n  definition of what works is likely the [automated workflow\nfiles](https://github.com/COVESA/ifex/tree/master/.github/workflows)\nor [tox.ini](./tox.ini))\n* Dependencies installed according to instructions below\n\n### Container use\n\nAs an alternative to installation instructions below, all the installations can also be hidden in a container.  Refer to the [README in the packaging/docker/ directory](./packaging/docker/README.md) for running the tools using containers instead.\n\n## Installing and use python version(s) with `pyenv`\n\nNOTE: Pyenv can set up virtual environments but is often considered not the best\nchoice for that, and we don't use it that way.  Pyenv's most important function\nis to download, compile, and install a particular python version from source\ncode.  If your system python version is one that is not supported by this\nproject and you are not able to install the right python version using another\nmethod, then Pyenv can be used.  It can be used in combination with\nvirtual-environment handlers, to get access to different python versions.\n\nIf [`pyenv` shell command](https://github.com/pyenv/pyenv) is not installed, use its [installer](https://github.com/pyenv/pyenv-installer) to get it:\n\n```bash\n   curl https://pyenv.run | bash  # download and install (YOU are responsible to check the script content)\n   exec $SHELL                    # restart your shell using the new $PATH\n```\n\nActivate a version in the current environment\n```sh\npyenv local 3.10.6\n```\n\n### Setup a python virtual environment (recommended)\n\nOnce you have an appropriate version of python, a virtual environment is\nrecommended to avoid any particulars in the main system installation.\n\nGo to project directory and then:\n```sh\npython -m venv venv\nsource venv/bin/activate\n```\n\nNEXT: Go to **Installing packages**\n\n### Setup without virtual environment (not recommended)\n\nGo directly to Installing packages\n\n### Setup and run tests using tox\n\nTox is another way to set up the working environment.  It is primarily used to test the program using multiple python versions.\n\n1. Install tox\n2. Install pyenv (most likely needed, use it if additional python versions are required)\n3. (optional) edit the provided tox.ini file\n4. Run tox  -- this will execute pytest for all stated python versions\n\nHere we provide a script that will check which versions are requested by `tox.ini`, and install all of those versions first, using pyenv:\n\n```bash\n   pip install \"tox\u003e=4\"\n   scripts/pyenv_install_for_tox.sh\n   tox\n```\nNote:  In this case, tox takes care of calling `pip` and `setup.py` to install the required packages.\n\n## Installing packages\n\n(for any or none, virtual-environment -- but not needed if using tox)\n\nRegardless of which type of virtual environment (if any) you use, it is required to install the IFEX package into your python environment, and to install needed dependencies with pip.\n\n0. **If you use a virtual environment, remember to first activate it!**  \nFor example:\n```\nsource venv/bin/activate\n```\n\n1. Install dependencies:\n```\npip install -r requirements.txt\n```\n\n2. Install the IFEX provided modules into your virtual environment\nThe following installs the package in develop mode (using setup.py)\n```\npip install -e .\n```\n\n## Trying it out\n\nInstalling the IFEX tools using `setup.py` creates some convenient\nexecutable shims, e.g. `ifexgen`, `ifexgen_dbus`, `ifexconv_protobuf`, ...\n\nIf those commands are not in your environment, try setting up python virtual environment and make sure pip install -e (setup.py) runs correctly.  After that, they should be in the `$PATH` variable and possible to run.\n\nTo run a generic code generator and specify an output template:\n\n```\nusage: ifexgen [-h] -d templates-dir-name ifex-input-file\n```\nTo get some test IFEX files, clone the VSC repo:\n\n```bash\n   git clone https://github.com/COVESA/vehicle_service_catalog\n\n   # Using a template\n   ifexgen vehicle_service_catalog/comfort-service.yml -d dtdl \n\n   # D-Bus:\n   ifexgen_dbus vehicle_service_catalog/comfort-service.yml\n```\n\nTo test some \u003cother\u003e-to-IFEX conversion, for example **gRPC/protobuf**:\n\n```bash\n   git clone https://github.com/COVESA/uservices\n   ifexconv_protobuf uservices/src/main/proto/vehicle/propulsion/engine/v1/engine_service.proto \u003eengine_service.ifex\n```\n\nTo try the D-Bus XML generator:\n```\nusage: ifexgen_dbus input_ifex.yaml\n```\n\n# Unit Tests\n\nThe project uses pytest to define unit tests. A starting point is in the tests\ndirectory and more can be added.\n\nTo run tests, just run pytest in the root directory, (optionally specify the tests directory).\n\n```bash\n   pytest -v tests\n```\n\n# Contribution\n\nPropose changes using the GitHub Issues or Pull Request.\n\n# Development\n\nMake sure you have read the [Specification](https://covesa.github.io/ifex/developers-manual)\nThen please refer to the [developer documentation](https://covesa.github.io/ifex/developers-manual)\n\n# Future plans, new proposals and enhancements\n\nPlease refer to [GitHub tickets](https://github.com/COVESA/ifex/issues)\n(Feel free to make a proposal or ask a question)\n\n# Known bugs\n\nPlease refer to [GitHub tickets](https://github.com/COVESA/ifex/issues)\nwith the label \"bug\"\n\n# Troubleshooting\n\nVarious tips to consider:\n\n* If the installation (pip install) is executed behind a (corporate) proxy, the following environments variables must be set: `http_proxy` and `https_proxy` (including authentication e.g., `http://${proxy_username):$(proxy_password)@yourproxy.yourdomain`)\n* If you use a custom pip installation directory, set the `PYTHONPATH` environment variable to the directory that you set in the `pip.ini` file.\n* If you do not run with administration rights, you may need to configure pip target path to write to your user home directory or consider using one of the `virtual environment` methods.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcovesa%2Fifex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcovesa%2Fifex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcovesa%2Fifex/lists"}