Warning

The FHIR build process is used by a small group of HL7 insiders who actually contribute to the specification itself. The build process requires a particular java set up, and is not particularly robust. If you are an implementer who is interested in using FHIR in a healthcare related product, there is no reason for you to be using the FHIR build process - anything that is useful for implementation is published through the specification itself.

  • Question: what if I need to make my own resources?
    • Answer: well, you'll have to use the build process then - but this is not supported, you'll find managing change control difficult, and it's not the intention that the build process be used to support you making your own resources. There is a work item for describing the governance, policy, and procedures around people making their own resources, and then making the tooling for that. Probable delivery Spring 2014 (northern hemisphere)

Set up

To create or maintain resources, you need to take a number of steps:

  1. Get "committer" access for https://github.com/hl7/fhir
    1. Get a Github account, if you don't already have one.
    2. Get commit privileges for FHIR by contacting one of the FHIR Management Group co-chairs. (Let them know your Github user id)
      1. As part of your email requesting commit privileges, please indicate in your email that you understand and agree to abide by the Intellectual Property rules as defined by the HL7 Governance and Operations Manual (GOM) (at the time of this writing, section 16 of the GOM)
      2. You will also need to indicate that you've signed up for the Committers/Announce thread on chat.fhir.org and agree to monitor it for changes to commit rules
    3. Share your github username and install a git client following the instructions at https://github.com/hl7/fhir/wiki/Get-Started-with-FHIR-on-GitHub.
    4. Make sure you have an HL7 Account to access Confluence and JIRA, as you'll need to coordinate changes to the build with JIRA trackers
  1. Prepare to run a build
    1. Note: if you prefer to run the build process in a Docker container, see instructions at https://github.com/FHIR/auto-ig-builder/tree/master/images/ig-publisher-base#build-the-core-fhir-spec; otherwise, proceed by installing the following requirements on your host system.)
    2. The build requires at least 16GB of RAM. It will build more quickly with more memory. 
    3. Ensure you have 64 Bit Java SDK installed on your machine
      1. Note: A JVM (jre) is not sufficient. You MUST have a Java SDK (jdk)
      2. Note: Java SDK versions older than Java 17 may not work; Grahame uses and debugs with Java 17
    4. You may also need to add a new JAVA environment variable
      1. JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF-8"
    5. Clone the FHIR source repository (https://github.com/hl7/fhir) into a local directory of your choice.
  2. Run the build
      • NOTE: the first build will seem to take a long time - specially if you are on a slow internet connection because the build will download additional requirements. My first build output 3970 lines of text.
    2. Launch either the publish.bat or publish.sh depending on your environment

The result should look something like this:

Running publication process now
Using C:\Program Files\java\jdk-11.0.10

> Configure project :

Kicking off FHIR publishing job!

==============================
Generating code using kindling version 1.0.1-SNAPSHOT
For more information on kindling, and to check latest version, check here:
https://github.com/HL7/kindling
==============================

> Task :publish
Publish FHIR in folder C:\Users\lloyd\Documents\SVN\fhir @ Mon, Oct 4, 2021 21:37-0600 0.016   0sec   18MB
Build local copy                                                           0.032   0sec   20MB
Detected Java version: 11.0.10 from C:\Program Files\Java\jdk-11.0.10 on amd64   0.0   0sec   20MB
Load UTG Terminology                                                       1.697   1sec   39MB
Load Package hl7.terminology#1.0.0
Load Terminology Cache from C:\Users\lloyd\Documents\SVN\fhir\vscache      0.557   2sec  125MB
  .. loaded                                                                3.747   6sec 2334MB
Checking Source for C:\Users\lloyd\Documents\SVN\fhir                      0.004   6sec 2334MB
Full Build                                                                 1.846   7sec 2358MB
Version 4.6.0-6f8bbe84e4
Load Loinc                                                                 2.107  10sec 2364MB
....
This was a Full Build                                                      0.247 1380sec 1943MB
Finished publishing FHIR @ Mon, Oct 4, 2021 22:00-0600                     0.497 1381sec 1943MB

BUILD SUCCESSFUL in 23m 3s
1 actionable task: 1 executed
Press any key to continue . . .


Note: The build time is influenced significantly by memory.  Also, an SDD is highly recommended.  After completing the build, expect the build folder to take > 4GB on your hard drive.

Build Parameters

The build program (tools.jar) has a mandatory first parameter which is the name of the root folder containing the build directory. (Actually, technically, it's not mandatory, it defaults to the current directory, but this is a little unpredictable across systems, so it should be filled out for certainty).

Other optional parameters (any order):

  • -nogen: don't generate the spec, just run the validation. (to use this, manually fix things in the publication directory, and then migrate the changes back to source when done. this is a hack)
  • -noarchive: don't generate the archive. Don't use this if you're a core editor
  • -web: produce the HL7 ready publication form for final upload (only core editors)
  • -diff: the executable program to use if platform round-tripping doesn't produce identical content (default: c:\program files (x86)\WinMerge\WinMergeU.exe)
  • -name: the "name" to go in the title bar of each of the specification

Build Policies

Failure to adhere to these policies will annoy (and create unwelcome additional work for) your fellow FHIR developers. Repeated violations may eventually result in revocation of commit privileges.

  1. Don't commit content until you've run a build and confirmed you haven't broken anything
  2. Don't make changes other than minor grammar, spelling or formatting changes to resource or other source files you don't "own"
    1. Exception: You can make changes to resource references if you've renamed a resource someone else is pointing to
  3. Commit regularly, ideally at least once a week so others, including the FHIR Management Group can keep track of what you're doing
    1. Be sure to respect rule #1 though
  4. Don't commit content during ballot/connectathon freeze periods as announced on the FHIR developers list unless discussed with core team
  5. All commits to the "source" directory must reference a Jira tracker number related to the change being made.
    1. Format is [#123] where 123 is the number of the change tracker item
    2. If an appropriate tracker record doesn't exist, you'll need to create one. (Be sure to update the tracker to indicate the change has been applied when work is complete)
    3. All commits relating to resources new for the 2nd DSTU release can be assigned to #2991
  6. When committing, try to provide a semi-descriptive explanation of what you've done
  7. Committing in small batches makes it easier to have meaningful commit descriptions
  8. If you do an update and find someone else has broken the build, feel free to publicly scold and mock them on the FHIR developers list
    1. You'd be wise to double-check that the problem is their content (not your own) before scolding and mocking . . .
    2. And, as a near term work around, you can revert to a previous version of the broken content
  • No labels