Skip to content

Commit

Permalink
update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@gilesknap
gilesknap committed Apr 9, 2024
1 parent 92ebc46 commit 2f158b1
Show file tree
Hide file tree
Showing 2 changed files with 63 additions and 26 deletions.
62 changes: 50 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,26 +7,64 @@

Converts EPICS vdct templates to pure msi compatible EPICS db templates

This is where you should write a short paragraph that describes what your module does,
how it does it, and why people should use it.
This tool is designed to modify an EPICS support module in order to remove
its dependency on the vdct tool. This is useful for support modules that we
want to build with the upstream vanilla EPICS base that does not include vdct.

Source | <https://github.com/epics-containers/vdct2template>
:---: | :---:
PyPI | `pip install vdct2template`
Releases | <https://github.com/epics-containers/vdct2template/releases>

This is where you should put some images or code snippets that illustrate
some relevant examples. If it is a library then you might put some
introductory code here:

```python
from vdct2template import __version__
## Installation

print(f"Hello vdct2template {__version__}")
```
To install the latest release from PyPI, create a virtual environment and
pip install like this:

Or if it is a commandline tool then you might put some example commands here:
```bash
python -m venv venv
source venv/bin/activate

pip install vdct2template
```
python -m vdct2template --version
```

## Usage

<pre>$ vdct2template --help
<b> </b>
<b> </b><font color="#A2734C"><b>Usage: </b></font><b>vdct2template [OPTIONS] FOLDER </b>
<b> </b>
<b>VDCT to template conversion function.</b>

<font color="#A2734C"><b> • </b></font><font color="#AAAAAA">This function assumes that all referenced VDCT files in the expand() blocks will be </font>
<font color="#A2734C"><b> </b></font><font color="#AAAAAA">in the same folder. </font>
<font color="#A2734C"><b> • </b></font><font color="#AAAAAA">We can use the builder.py file to check for direct references to template files Use </font>
<font color="#A2734C"><b> </b></font><font color="#AAAAAA">--no-use-builder to disable this feature. Direct references to a template file is an </font>
<font color="#A2734C"><b> </b></font><font color="#AAAAAA">error because we need to modify all macro names to add a _ prefix in templated files. </font>
<font color="#A2734C"><b> • </b></font><font color="#AAAAAA">Files referenced in expand() blocks will have their macro names updated to all have a </font>
<font color="#A2734C"><b> </b></font><font color="#AAAAAA">_ prefix, because MSI does not support substituting a macro with it&apos;s own name and </font>
<font color="#A2734C"><b> </b></font><font color="#AAAAAA">passing a default. This is a workaround to that limitation. </font>
<font color="#A2734C"><b> • </b></font><font color="#AAAAAA">The original expands() block is replaced with a series of substitute MSI directives </font>
<font color="#A2734C"><b> </b></font><font color="#AAAAAA">and an include MSI directive. </font>
<font color="#A2734C"><b> • </b></font><font color="#AAAAAA">The resulting set of templates can be expanded natively by MSI without the need for </font>
<font color="#A2734C"><b> </b></font><font color="#AAAAAA">VDCT. </font>
<font color="#A2734C"><b> • </b></font><font color="#AAAAAA">The DB files created by such an expansion should be equivalent to the original VDCT </font>
<font color="#A2734C"><b> </b></font><font color="#AAAAAA">generated ones. </font>

<font color="#AAAAAA">╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮</font>
<font color="#AAAAAA">│ </font><font color="#C01C28">*</font> folder <font color="#A2734C"><b>DIRECTORY</b></font> folder of vdb files to convert to template files. │
<font color="#AAAAAA">│ [default: None] │</font>
<font color="#AAAAAA">│ </font><font color="#80121A">[required] </font> │
<font color="#AAAAAA">╰────────────────────────────────────────────────────────────────────────────────────────╯</font>
<font color="#AAAAAA">╭─ Options ──────────────────────────────────────────────────────────────────────────────╮</font>
<font color="#AAAAAA">│ </font><font color="#2AA1B3"><b>--version</b></font> <font color="#A2734C"><b> </b></font> Print the version and exit │
<font color="#AAAAAA">│ </font><font color="#2AA1B3"><b>--use-builder</b></font> <font color="#A347BA"><b>--no-use-builder</b></font> <font color="#A2734C"><b> </b></font> Use the builder.py file to look for │
<font color="#AAAAAA">│ direct references to template files. │</font>
<font color="#AAAAAA">│ [default: use-builder] │</font>
<font color="#AAAAAA">│ </font><font color="#2AA1B3"><b>--builder</b></font> <font color="#A2734C"><b>FILE</b></font> Path to the builder file. │
<font color="#AAAAAA">│ [default: None] │</font>
<font color="#AAAAAA">│ </font><font color="#2AA1B3"><b>--help</b></font> <font color="#A2734C"><b> </b></font> Show this message and exit. │
<font color="#AAAAAA">╰────────────────────────────────────────────────────────────────────────────────────────╯</font>

</pre>
27 changes: 13 additions & 14 deletions src/vdct2template/__main__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
__all__ = ["main"]


cli = typer.Typer()
cli = typer.Typer(rich_markup_mode="markdown")


def version_callback(value: bool):
Expand Down Expand Up @@ -47,29 +47,28 @@ def main(
),
):
"""
VDCT to template conversion function.
### VDCT to template conversion function.
Converts all VDCT files in the folder to template files.
This function assumes that all referenced VDCT files in the expand() blocks
- This function assumes that all referenced VDCT files in the expand() blocks
will be in the same folder.
We can use the builder.py file to check for direct references to template files
- We can use the builder.py file to check for direct references to template files
Use --no-use-builder to disable this feature. Direct references to a template
file is an error because we need to modify all macro names to add a _ prefix
in templated files.
This tool converts VDCT files to template files. It looks for expand() blocks
in the VDCT files. If these are found then it will also convert all of the
referenced files to template files. In referenced files the macro names will
all have _ prefix added because MSI does not support substituting a macro with
- Files referenced in expand() blocks will have their macro names updated to
all have a _ prefix, because MSI does not support substituting a macro with
it's own name and passing a default. This is a workaround to that limitation.
The original expands() block is replaced with a series of substitute
and include MSI directives.
- The original expands() block is replaced with a series of substitute
MSI directives and an include MSI directive.
- The resulting set of templates can be expanded natively by MSI without the
need for VDCT.
The resulting set of templates can be expanded natively by MSI without the
need for VDCT. The resulting DB files should be equivalent to the original.
- The DB files created by such an expansion should be equivalent to the
original VDCT generated ones.
"""

if use_builder:
Expand Down

0 comments on commit 2f158b1

Please sign in to comment.