Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Use dedicated README file for PackerCLI project #563

Merged
merged 2 commits into from
Sep 24, 2024
Merged

docs: Use dedicated README file for PackerCLI project #563

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
755978d
docs: Use dedicated README file for PackerCLI project
and-hus Sep 23, 2024
40b35d2
Merge branch 'develop-2.0' into docs/packagerReadme
baseTwo Sep 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 9 additions & 4 deletions Cql/PackagerCLI/PackagerCLI.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,12 @@
</PropertyGroup>

<ItemGroup>
<None Include="$(OutputPath)\build.log" Link="build.log" />
<None Remove="..\..\README.md" />
<None Include="README.md" Pack="true" PackagePath=""/>
</ItemGroup>

<ItemGroup>
<None Include="$(OutputPath)\build.log" Link="build.log" />
</ItemGroup>

<ItemGroup>
Expand Down Expand Up @@ -44,9 +49,9 @@
</ItemGroup>

<ItemGroup>
<Compile Update="CqlPackagingPipelineOptions.*.cs">
<DependentUpon>CqlPackagingPipelineOptions.cs</DependentUpon>
</Compile>
<Compile Update="CqlPackagingPipelineOptions.*.cs">
<DependentUpon>CqlPackagingPipelineOptions.cs</DependentUpon>
</Compile>
</ItemGroup>

</Project>
62 changes: 62 additions & 0 deletions Cql/PackagerCLI/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# HL7 CQL Packager

A .NET tool that packages CQL, ELM, and build outputs into a FHIR Library resource.

## Overview

The HL7 CQL Packager performs the following steps:

1. **Translation**: Converts ELM JSON files into Linq.Expressions, then translates these expressions into C# code. Each ELM file is converted into a class, with each function within that file becoming a public method in the class.
2. **Compilation**: Compiles the generated C# code into a single assembly per ELM file.
3. **Packaging**: Packages the assembly (and optionally the original CQL, ELM, and C# source code) into a FHIR Library resource, creating one resource per original ELM file.

## Getting Started

### Installation

Install the packager tool globally using the following command:

```shell
dotnet tool install Hl7.Cql.Packager --global --prerelease
baseTwo marked this conversation as resolved.
Show resolved Hide resolved
```

> **Note**: The `--prerelease` option is required because only prerelease versions are currently available.

### Prerequisites

The tool does not convert CQL into ELM. You need to use the existing Java-based tooling for this conversion.

## Usage

Run the tool with the following command:

```shell
cql-package --elm <directory> --cql <directory> [options]
baseTwo marked this conversation as resolved.
Show resolved Hide resolved
```

### Mandatory Parameters

- `--elm <directory>`: Specifies the root directory for the ELM files. This parameter is required.
- `--cql <directory>`: Specifies the root directory for the CQL files. This parameter is required.

### Optional Parameters

- `[--fhir <directory>]`: Specifies the output directory for the FHIR resources
- `[--cs <directory>]`: Specifies the output directory for generated C# code
- `[--cs-typeformat <var|explicit>]`: Specifies whether to use 'var' (default) or explicit types in the generated C# output
- `[--dll <directory>]`: Specifies the DLL output directory
- `[--log-debug <true|false>]`: Enable debug logging or not (default)
- `[--canonical-root-url <url>]`: Specifies the root url used for the resource canonical. If omitted a '#' will be used.
- `[--override-utc-date-time <ISO8601-date-time>]`: Defines the UTC date to override in the generated FHIR resource libraries (example: 2000-12-31T23:59:59.99Z). If omitted the current date time will be used.

### Example

```
cql-package --elm Elm\json --cql Cql\input --fhir c:\packager-output-fhir --cs c:\packager-output-cs
baseTwo marked this conversation as resolved.
Show resolved Hide resolved
```

This command packages the ELM and CQL files from the specified directories and writes the generated FHIR Resources and C# code to the respective directories.

## Further Reading

The CQL Packager tool is part of the [Firely CQL SDK](https://github.com/FirelyTeam/firely-cql-sdk). More information can be found at [Firely’s documentation site](https://docs.fire.ly/projects/Firely-NET-SDK/en/latest/cql/cql-packager.html).