FHIR Build Process

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. 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
   4. 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
4. 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. When committing, try to provide a semi-descriptive explanation of what you've done
6. Committing in small batches makes it easier to have meaningful commit descriptions
7. 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