diff --git a/README.md b/README.md index 2cd8b9e5f..06b53edea 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # fhir-codegen -A .Net library and related utilities to work with FHIR specifications. +A .Net application, library, and related utilities to work with FHIR specifications. # Documentation @@ -10,17 +10,30 @@ Detailed documentation can be found on the [documentation site](https://microsof Project source code is hosted on [GitHub](https://github.com/microsoft/fhir-codegen). -All projects are currently built on .Net 7.0 and tested on multiple platforms, though Windows is the primary development platform. The .Net 6.0 SDK and runtimes are available for free at: https://dotnet.microsoft.com/en-us/download . +All projects are currently built on .Net 8.0 and tested on multiple platforms, though Windows is the primary development platform. The +.Net 8.0 SDK and runtimes are available for free at: https://dotnet.microsoft.com/en-us/download . ## Microsoft.Health.Fhir.CodeGenCommon -This project is a class library that contains the common (normalized) models used in these projects. The project is lightweight and used to ensure that additional projects (e.g., a WASM UI) have access to all the models. +This project is a class library that contains the common (normalized) models used in these projects. The project is lightweight with +minimal dependencies and used to ensure that additional projects and external development have access to models. Detailed information about the models can be found in the [Common Models Documentation](https://microsoft.github.io/fhir-codegen/api/Microsoft.Health.Fhir.CodeGenCommon.Models.html). -## Microsoft.Health.Fhir.SpecManager +## Microsoft.Health.Fhir.CrossVersion -This project is a class library that contains the logic used in the various projects. For example, this project contains the code to: +This project is a class library that provides *basic* support for loading specifications from multiple versions of FHIR. The library is scoped +to the needs of this project and is not intended to be a full FHIR library. It is incomplete in support, though we do plan on expanding in the +future. + +## Microsoft.Health.Fhir.MappingLanguage + +This project is a class library that provides support for working with the FHIR Mapping Language (FML). Today, content is focused on parsing FML +and providing useful abstractions for consumption. + +## Microsoft.Health.Fhir.CodeGen + +This project is a class library that contains the logic used to process FHIR specifications. For example, this project contains the code to: * download packages, * resolve canonical URLs, * normalize different versions of FHIR, @@ -33,78 +46,74 @@ More information about this project can be found in the [API Documentation](http ### Export Languages -The projects in this repository can be used to translate FHIR packages (core or IG) into other forms - e.g., programming language definitions (C#, TypeScript, etc.), or data files for consumption (Info, Cytoscape, etc.). +The projects in this repository can be used to translate FHIR packages (core or IG) into other forms - e.g., programming language definitions +(C#, TypeScript, Ruby, etc.), other language definitions (FHIR Shorthand, OpenAPI, etc.), or data formats (Info text, etc.). -More information about current languages can be found on the [Export Languages Page](https://microsoft.github.io/fhir-codegen/articles/languages.html). Information about adding new languages can be found on the [Extending Page](https://microsoft.github.io/fhir-codegen/articles/extending.html). +More information about current languages can be found on the [Export Languages Page](https://microsoft.github.io/fhir-codegen/articles/languages.html). +Information about adding new languages can be found on the [Extending Page](https://microsoft.github.io/fhir-codegen/articles/extending.html). -## FhirCodeGenBlazor - -This project is a server-side Blazor application that can be used to interact with the code-generation library. Generally, it can: -* manage the FHIR Package Cache (`~/.fhir`) - add/update/remove packages -* browse package artifacts -* search across element information (e.g., resource/logical models elements) -* compare packages or artifacts (Diff Tool) -* perform exports -* etc. - -To run this project from a command line: -* `dotnet run --project src/FhirCodeGenBlazor/FhirCodeGenBlazor.csproj` -or, you can build a release version to run: -* `dotnet build src/FhirCodeGenBlazor/FhirCodeGenBlazor.csproj -c Release` -* `dotnet ./src/FhirCodeGenBlazor/bin/Release/net7.0/FhirCodeGenBlazor.dll` - -More information about this project can be found in the [API Documentation](https://microsoft.github.io/fhir-codegen/api/index.html). - -More information about this project can be found in the [Blazor UI Documentation](https://microsoft.github.io/fhir-codegen/articles/blazorui.html). - - -## fhir-codegen-cli +## fhir-codegen This project is a command-line application that can be used to perform export operations (e.g., for CI Pipelines). Generally, it can: * manage the FHIR Package Cache (`~/.fhir`) - add/update packages * perform exports / transforms of FHIR packages +* compare specification packages To run this project from a command line: -* `dotnet run --project src/fhir-codegen-cli/fhir-codegen-cli.csproj -- [options]` -or, you can build a release version to run: -* `dotnet build src/fhir-codegen-cli/fhir-codegen-cli.csproj -c Release` -* `dotnet ./src/fhir-codegen-cli/bin/Release/net7.0/fhir-codegen-cli.dll` +* `dotnet run --project src/fhir-codegen-cli/fhir-codegen-cli.csproj -- [command] [options]` +or you can build a release version to run: +* `dotnet build -c Release` +* `./src/fhir-codegen/bin/Release/net8.0/fhir-codegen-cli.exe` ``` +Description: + A utility for processing FHIR packages into other formats/languages. + Usage: - fhir-codegen-cli [options] + fhir-codegen [command] [options] Options: - -o, --output-path File or directory to write output. - --package-directory The path to a local directory for FHIR packages, if different than the default - FHIR cache (~/.fhir); e.g., (.../fhirPackages)). - -l, --language Name of the language to export (default: Info|TypeScript|CSharpBasic). - --language-help Display languages and their options. [default: False] - --language-options, --opts Language specific options, see documentation for more details. Example: - Lang1|opt=a|opt2=b|Lang2|opt=tt|opt3=oo. - --language-input-dir The full path to a local directory to pass additional content to languages. - --offline-mode Offline mode (will not download missing packages). [default: False] - -k, --export-keys '|' separated list of items to export (not present to export everything). - --official-expansions-only Set to restrict value-sets to only official expansions. [default: False] - --experimental, --include-experimental If the output should include structures marked experimental. [default: False] - --export-types, --types Types of FHIR structures to export (primitive|complex|resource|interaction|enum), - default is all. - --extension-support The level of extensions to include (none|official|officialNonPrimitive|nonPrimitive|all), - default is nonPrimitive. - --fhir-server-url, --server FHIR Server URL to pull a CapabilityStatement or Conformance from. The server - must provide application/fhir+json support. - -p, --packages '|' separated list of packages, with or without version numbers, - e.g., hl7.fhir.r4.core#4.0.1|hl7.fhir.us.core#latest. - --load-DSTU2, --load-r2 If FHIR DSTU2 should be loaded, which version (e.g., 1.0.2 or latest) - --load-r3, --load-STU3 If FHIR STU3 should be loaded, which version (e.g., 3.0.2 or latest) - --load-r4 If FHIR R4 should be loaded, which version (e.g., 4.0.1 or latest) - --load-r4b If FHIR R4B should be loaded, which version (e.g., 4.3.0 or latest) - --load-r5 If FHIR R5 should be loaded, which version (e.g., 5.0.0-ballot or latest) - --ci-branch If loading from the CI server, the name of the branch to use. - -v, --verbose Show verbose output. [default: False] - --version Show version information - -?, -h, --help Show help and usage information + --fhir-cache Location of the FHIR cache (none specified defaults to user .fhir directory). [] + --use-official-registries Use official FHIR registries to resolve packages. [] + --additional-fhir-registry-urls Additional FHIR registry URLs to use. [] + --additional-npm-registry-urls Additional NPM registry URLs to use. [] + --output-dir, --output-directory, --output-path File or directory to write output. [] + --output-filename Filename to write output. [] + -p, --load-package, --package Package to load, either as directive ([name]#[version/literal]) or URL. [] + --auto-load-expansions When loading core packages, load the expansions packages automatically. [] + --resolve-dependencies Resolve package dependencies. [] + --load-structures Types of FHIR structures to load. [] + opt: CapabilityStatement + opt: CodeSystem + opt: Compartment + opt: ComplexType + opt: ConceptMap + opt: Extension + opt: ImplementationGuide + opt: Interface + opt: LogicalModel + opt: NamingSystem + opt: Operation + opt: PrimitiveType + opt: Profile + opt: Resource + opt: SearchParameter + opt: StructureMap + opt: Unknown + opt: ValueSet + + --export-keys Keys of FHIR structures to export (e.g., Patient), empty means all. [] + --load-canonical-examples Load canonical examples from packages. [] + --offline Offline mode (will not download missing packages). [] + --fhir-version FHIR version to use. [] + --version Show version information + -?, -h, --help Show help and usage information + +Commands: + generate Generate output from a FHIR package and exit. + compare Compare two sets of packages. + gui Launch the GUI (experimental). ``` More information about this project can be found in the [Command Line Documentation](https://microsoft.github.io/fhir-codegen/articles/cli.html). @@ -112,59 +121,13 @@ More information about this project can be found in the [Command Line Documentat ### Examples * Download and parse FHIR R4 (latest published version) into the user FHIR cache, then build a TypeScript file in the current directory - * `fhir-codegen-cli -p hl7.fhir.r4#latest --language TypeScript --output-path ./R4.ts` + * `fhir-codegen generate TypeScript -p hl7.fhir.r4.core --output-path ./R4.ts` * Download and parse FHIR R4 (latest published version) into the user FHIR cache, then build a TypeScript file in the current directory, restricted to just the Resources: Patient, Encounter, and Observation - * `fhir-codegen-cli --load-r4 latest --language TypeScript --output-path ./R4.ts --export-keys Patient|Encounter|Observation` + * `fhir-codegen generate TypeScript -p hl7.fhir.r4.core --output-path ./R4.ts --export-keys Patient|Encounter|Observation` -* Download and parse the latest published version of each FHIR release into the user FHIR cache, then build a C# file for each in ./cs - * `fhir-codegen-cli --load-r2 latest --load-r3 latest --load-r4 latest --load-r5 latest --language CSharpBasic --output-path ./cs` - -* Download and parse FHIR R4 (latest published version) into the user FHIR cache, then build a C# file in the current directory using the namespace: MyOrg.MyProject.Fhir - * `fhir-codegen-cli -p hl7.fhir.r4#latest --language CSharpBasic --output-path ./cs/R4.cs --language-options CSharpBasic|namespace=MyOrg.MyProject.Fhir` - -## fhir-codegen-test-cli - -This project is a **minimal** test harness for generated TypeScript and CSharp code. It can be used to ensure that the core parsing and generation is working properly, and potentially as an example for other language outputs. - -To run this project from a command line: -* `dotnet run --project src/fhir-codegen-test-cli/fhir-codegen-test-cli.csproj -- [options]` - -It will use generated CSharpBasic and TypeScript files for FHIR Versions DSTU2, STU3, R4, and R5. It will then run each through a build process (requires `dotnet` for C# and `tsc` for TypeScript) to validate there are no syntax errors in any of the generated files. - -Note that this test takes several minutes to run. - -## Usage -``` -fhir-codegen-test-cli: - The FHIR CodeGen Test CLI. - -Usage: - fhir-codegen-test-cli [options] - -Options: - --repo-root-path The path to the repository root (if not CWD). - --verbose True to display all output (default: false) - --fixed-format-statistics True to output *only* test run statistics: - #run[tab]#passed[tab]#failed[tab]#skipped - (default: false) - --errors-to-std-error True to write errors to stderr instead of stdout. - (default: False) - --version Show version information - -?, -h, --help Show help and usage information -``` - -## Requirements - -In order to run TypeScript tests, the system must be able to find the 'tsc' (TypeScript compile) command. Note that it must be installed and accessible by the test application (e.g., `npm install -g typescript`). - -## fhirCsR2 - -This is a library project used to isolate the FHIR DSTU2 definitions. All other versions of FHIR are dynamically parsed, but there has not been justification to port this forward - no technical corrections for DSTU2 are expected, so this is *mostly* considered legacy. - -# Pre-Generated Files - -The `generated` directory has static outputs for each of the supported versions of FHIR, in some of the supported languages. These files are used to validate changes to the core loading and parsing, but may be useful otherwise. +* Download and parse FHIR R4 (latest published version) into the user FHIR cache, reach out the Firely Test Server, and build a set of OpenAPI definitions + * `generate OpenApi --fhir-server-url http://server.fire.ly/r4 -p hl7.fhir.r4.core#4.0.1 --output-path ./FS-OpenApi-R4 --include-experimental --schema-level names --metadata true --multi-file true --single-responses false --resolve-server-canonicals false --resolve-external-canonicals false --basic-scopes-only true` # Contributing @@ -183,4 +146,4 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio # Trademarks -FHIR® is the registered trademark of HL7 and is used under Community Project guidelines. This project is not affiliated with, or approved or sponsored by, HL7. \ No newline at end of file +FHIR® is the registered trademark of HL7 and is used under Community Project guidelines. This project is not affiliated with, or approved or sponsored by, HL7.