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. Sign up to the FHIR Developers list server (fhirsvn@lists.hl7.org) (this is distinct from the FHIR list server). This ensures you'll receive updates about planned changes to the build process, outages, etc.
2. Get access to HL7's SVN environment and permission to edit FHIR resources
   1. Acquire an SVN client such as TortoiseSVN[1] or Eclipse
   2. Get an gForge account
   3. Get commit privileges for FHIR by contacting one of the FHIR Management Group co-chairs. (Let them know your gForge id)
3. Prepare to run a build
   1. Check out the FHIR project (http://gforge.hl7.org/svn/fhir/trunk/build) into a local directory of your choice (under trunk there are several directories that contain archives, documents, presentations and so forth that come to many MB of content not required to run the build program. You can sync either the trunk or the build)
   2. Ensure you have a current Java SDK installed on your machine (1.6)
      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

Ant is available from ant.apache.org

1. 1. 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
   2. 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
2. Run the build
   1. 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 - do not build the specification, just validate the examples (don't rebuild the examples either - just validate them in \publish. This typically means editing them in \publish, and then copying the edits in to the source directories once complete)
• -web - do the extra step that builds the HL7 web site ready version (paths are re-organised in the content generated for HL7 directory. Only specify this if you intend to do an upload - core team only)
• -diff [path] - use this as the nominated diff program when examples don't round trip perfectly (default on windows is WinMerge - it will be used if present)
• -debug - print a stack dump to system.err if build process terminates with an exception (typically means you can jump to the exception source code when running from an IDE such as eclipse)

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