FHIR Build Process

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 [1]
   1. Get an gForge account for participating in FHIR issue tracking discussion
   2. Get commit privileges for FHIR by contacting one of the FHIR Management Group co-chairs. (Let them know your gForge 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 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 [2].

1. Prepare to run a build
   1. Clone the FHIR source repository (https://github.com/hl7/fhir) into a local directory of your choice.
   2. Ensure you have the Java 8 SDK installed on your machine (1.8)
      1. Note: A JVM (jre) is not sufficient. You MUST have a Java SDK (jdk)
   3. Ensure you have ant installed and on your path
      1. Ant is available from ant.apache.org
      2. Change your path to include the "bin" directory of your Ant install.
   4. Optionally: make sure you have .NET 4.x available to compile the .NET reference implementations
      1. Get .NET from here: http://www.microsoft.com/en-us/download/details.aspx?id=40773
      2. Follow the text under 'Prerequisites' on this page: http://msdn.microsoft.com/en-us/library/vstudio/gg597391(v=vs.100).aspx
   5. You may need to edit the "publish.bat" or "publish.sh" file to point to your particular SDK. (and please don't commit this file)
      1. Just invoking "Java" based on your path will run the JVM rather than the SDK, as installing the SDK installs a JVM too
      2. we're still trying to figure this one out - stupid JAVA
   6. You may also need to add a new JAVA environment variable
      1. JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF-8"
      • Consider creating your own "mypublish.bat" or "mypublish.sh" file to add any external references you need - just dont add or commit it. This will allow you to rebuild the entire build, and still maintain your customization.
2. Run the build
   1. • 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
Publish FHIR in folder [Base FHIR folder]                                    0sec    6MB
Checking Source for [Base FHIR folder]                                       0sec    6MB
Loading                                                                      6sec   22MB
Load Concept Domains                                                         7sec   26MB
Validating                                                                  12sec   36MB
Produce delphi Reference Implementation                                     14sec   86MB
Produce java Reference Implementation                                       16sec  138MB
Produce csharp Reference Implementation                                     18sec   44MB
Produce ecore Reference Implementation                                      25sec   84MB
Compile java Reference Implementation                                       25sec   86MB
Produce Schemas                                                             35sec  114MB
Produce Content                                                             37sec  133MB
 ...resource [SomeResource]                                                 38sec  181MB
              ...
 ...diagram [SomeDiagram]                                                   99sec  292MB
              ...
 ...page [Some specification page].htm                                     100sec  190MB
              ...
 ...profile [Some profile]                                                 102sec  379MB
              ...
 ...summaries                                                              102sec  379MB
 ...zips                                                                   103sec  389MB
 ...zip                                                                    103sec  389MB
Produce Book Form                                                          114sec  112MB
Produce HL7 copy                                                           115sec  243MB
Produce Archive copy                                                       163sec  301MB
Validating XML                                                             179sec  662MB
.. Loading schemas                                                         179sec  662MB
.... done                                                                  190sec  680MB
Reference Platform Validation.                                             204sec  165MB
 ...validate [Some example]                                                204sec  165MB
              ...
Finished publishing FHIR                                                   232sec  126MB

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 gForge 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