Metadata-Version: 2.1
Name: eda-container-wrapper
Version: 0.0.4
Summary: Generic wrapper tool around open source EDA tools that runs Docker containers
Home-page: https://github.com/librecores/eda-container-wrapper
Author: Stefan Wallentowitz
Author-email: stefan@wallentowitz.de
License: UNKNOWN
Description: # EDA Container Wrapper
        
        EDA container wrapper is a work-in-progress generic wrapper tool around open
        source EDA tools. The tools are executed in Docker containers and this tool
        wraps this execution and keeps an inventory of tools.
        
        It supports three use cases:
        
        1. Run `eda-container-wrapper` to execute the wrapper with given parameters
        2. Let `eda-container-wrapper` create a wrapper script (in an executable path for example) with pre-defined settings
        3. Run tools from python using the `edacontainerwrapper` module
        
        The settings can be set in the following way in precedence order:
        
        1. As parameters to the `eda-container-wrapper` tool or to the respective functions of `edacontainerwrapper`
        2. As environment variables
        3. As default settings in the wrapper scripts
        
        ## Installation
        
        ```shell
        $ pip3 install eda-container-wrapper
        ```
        
        ## Supported settings
        
        ### Tool version (`--tool-version` or `ECW_TOOL_VERSION`, default: depends on tool)
        
        Sets the version of the tool to use.
        
        ### Interactive (`--non-interactive` or `ÈCW_INTERACTIVE`, default: interactive)
        
        Runs the Docker container in interactive mode (allowing to terminate it easily
        for example) with the Docker `-ti` flags. Some non-interactive environments such
        as CI don't support that (missing tty). Note the difference in logic, the
        default is interactive mode which is disabled with the `--non-interactive`
        switch. `ECW_INTERACTIVE` keeps it interactive when set to `true` or `1` and it
        will be non-interactive otherwise.
        
        ### Current work directory base (`--cwd-base` or `ECW_CWD_BASE`, default: not set)
        
        If not empty this is a colon-separated pair of a leading path of the cwd where
        the tool was called from and a replacement for this path. This is in particular
        useful when called from inside a Docker container, such as in CI. The syntax is:
        `<actual path>:<cwd path>`.
        
        ### Split the current working directory (`--split-cwd-tail` or `ECW_SPLIT_CWD_TAIL`, default: `0`)
        
        When mapping the current working directory, this setting actually maps the path
        up the hierarchy by the given value. This is in particular useful when you need
        to access data relative to the current working directory that is in upper and
        sibbling folders.
        
        For example, when started from the following folder:
        
        ```
        CWD=/path/to/my/project/build
        ```
        
        Setting `--split-cwd-tail=1` the split is into `/path/to/my/project` and
        `build`. Each tool has a "project path" that is the volume where the tool is
        executed in then by setting the working directory. For a tool with the project
        path `/project` it will then mount `/path/to/my/project` to `/project` and the
        workdir will be `/project/build`.
        
        This split is executed after processing the `cwd base`.
        
        ## Running a Tool
        
        As described above there are different ways to run a tool, that are described in
        the following.
        
        ### Run `eda-container-wrapper`
        
        The program is called with the parameters as described and the toolname.
        Following a `--` parameters to the tool can be supplied.
        
        Example:
        
        ```shell
        $ eda-container-wrapper verilator -- --version
        ```
        
        ### Create wrapper
        
        To create a `verilator` script that by default executes version 4.100:
        
        ```shell
        $ eda-container-wrapper --write-script=/usr/local/bin/verilator --tool-version 4.100 verilator
        ```
        
        and then execute it:
        
        ```shell
        $ verilator --version
        Verilator 4.100 2020-09-07 rev v4.100
        ```
        
        Setting the environment setting `ECW_TOOL_VERSION` changes the defualt behavior:
        
        ```shell
        $ ECW_TOOL_VERSION=4.102 verilator --version
        Verilator 4.102 2020-10-15 rev v4.102
        ```
        
        It can be useful to create the script in your virtual environment:
        
        ```shell
        $ eda-container-wrapper --write-script=$VIRTUAL_ENV/verilator --tool-version 4.100 verilator
        ```
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Topic :: Utilities
Description-Content-Type: text/markdown
