FHIR Build Process
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)
To create or maintain resources, you need to take a number of steps:
- Get "committer" access for https://github.com/hl7/fhir
- Get an gForge account for participating in FHIR issue tracking discussion
- Get commit privileges for FHIR by contacting one of the FHIR Management Group co-chairs. (Let them know your gForge id)
- 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)
- 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
- 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.
- Prepare to run a build
- Clone the FHIR source repository (https://github.com/hl7/fhir) into a local directory of your choice.
- Ensure you have the Java 8 SDK installed on your machine (1.8)
- Note: A JVM (jre) is not sufficient. You MUST have a Java SDK (jdk)
- Ensure you have ant installed and on your path
- Ant is available from ant.apache.org
- Change your path to include the "bin" directory of your Ant install.
- Install Jekyll in order to run the IGPublisher tests inside the main build. See Windows and Linux instructions.
- Optionally: make sure you have .NET 4.x available to compile the .NET reference implementations
- Get .NET from here: http://www.microsoft.com/en-us/download/details.aspx?id=40773
- Follow the text under 'Prerequisites' on this page: http://msdn.microsoft.com/en-us/library/vstudio/gg597391(v=vs.100).aspx
- 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)
- Just invoking "Java" based on your path will run the JVM rather than the SDK, as installing the SDK installs a JVM too
- we're still trying to figure this one out - stupid JAVA
- You may also need to add a new JAVA environment variable
- 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.
- 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.
- 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
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
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.
- Don't commit content until you've run a build and confirmed you haven't broken anything
- Don't make changes other than minor grammar, spelling or formatting changes to resource or other source files you don't "own"
- Exception: You can make changes to resource references if you've renamed a resource someone else is pointing to
- Commit regularly, ideally at least once a week so others, including the FHIR Management Group can keep track of what you're doing
- Be sure to respect rule #1 though
- Don't commit content during ballot/connectathon freeze periods as announced on the FHIR developers list unless discussed with core team
- All commits to the "source" directory must reference a gForge tracker number related to the change being made.
- Format is [#123] where 123 is the number of the change tracker item
- 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)
- All commits relating to resources new for the 2nd DSTU release can be assigned to #2991
- When committing, try to provide a semi-descriptive explanation of what you've done
- Committing in small batches makes it easier to have meaningful commit descriptions
- 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
- You'd be wise to double-check that the problem is their content (not your own) before scolding and mocking . . .
- And, as a near term work around, you can revert to a previous version of the broken content