From 445b62f0d4ec57a8473900d074a33fbd611c03f8 Mon Sep 17 00:00:00 2001 From: Bryan Herman Date: Fri, 11 Apr 2014 17:26:24 -0400 Subject: [PATCH] added documentation on working with FoX submodule --- docs/source/devguide/xml-parsing.rst | 82 +++++++++++++++++++++++++++- 1 file changed, 81 insertions(+), 1 deletion(-) diff --git a/docs/source/devguide/xml-parsing.rst b/docs/source/devguide/xml-parsing.rst index 8310d53e4e..cd2b6d4ae8 100644 --- a/docs/source/devguide/xml-parsing.rst +++ b/docs/source/devguide/xml-parsing.rst @@ -29,10 +29,90 @@ schema for the file you changed (e.g. src/relaxng/geometry.rnc) so that those who use Emacs can confirm whether their input is valid before they run. You will need to be familiar with RELAX NG `compact syntax`_. -.. _FoX: https://github.com/andreww/fox +Working with the FoX Submodule +============================== + +The FoX_ library is included as a submodule_ in OpenMC. This means that for a +given commit in OpenMC, there is an associated commit id that links to FoX. +The actual FoX source code is maintained at mit-crpg/fox, branch openmc. When +cloning the OpenMC repo for the first time, you will notice that the directory +*src/xml/fox* is empty. To fetch the submodule source code, you can manually +enter the following from the root directory of OpenMC: + +.. code-block:: sh + + git submodule init + git submodule update + +It should be noted that if the submodule is not initialized and updated, *cmake* +will automatically perform these commands if it cannot file the FoX source code. + +If you navigate into the FoX source code in OpenMC, src/xml/fox, and check git +information, you will notice that you are in a completely different repo. Actually, +you are in a clone of mit-crpg/fox. If you have write access to this repo, you can +make changes to the FoX source code, commit and push just like any other repo. +Just because you make changes to the FoX source code in OpenMC or in a standalone +repo, this does not mean that OpenMC will automatically fetch these changes. The +way submodules work is that they are just stored as a commit id. To save FoX xml +source changes to your OpenMC branch, do the following: + +1. Go into src/xml/fox and check out the appropriate source code state + +2. Navigate back out of fox subdirectory and type: + +.. code-block:: sh + + git status + +3. Make sure you see that git recognized that the state of FoX changed: + +:: + + # On branch fox_submodule + # Changes not staged for commit: + # (use "git add ..." to update what will be committed) + # (use "git checkout -- ..." to discard changes in working directory) + # + # modified: fox (new commits) + +4. Commit and push this change + +Editing FoX on Personal Fork +============================ + +If you don't have write access to mit-crpg/fox and thus can't make a branch off of the openmc +branch there, you will need to fork mit-crpg/fox to your personal account. You need to then +link your branch in your OpenMC repo, to the *openmc* branch on your own personal FoX fork. +To do this, edit the *.gitmodules* file in the root folder of the repo. It contains the +following information: + +:: + + [submodule "src/xml/fox"] + path = src/xml/fox + url = git@github.com:mit-crpg/fox + +Change the url remote to your own fork. The commit id should stay constant until you start +making modification to FoX yourself. Once you have made changes to your FoX fork and linked +the new commit id to your OpenMC branch, you can pull request your changes in by peforming +the following steps: + +1. Create a pull request from your fork of FoX to mit-crpg/fox and wait until it is merged +into the openmc branch. + +2. In your OpenMC repo, change your *.gitmodules* file back to point at mit-crpg/fox. + +3. Submit a pull request to mit-crpg/openmc + +.. warning:: If you make changes to your FoX submodule inside of an OpenMC repo and do not + commit, do **not** run *git submodule update*. This may throw away any changes that + were not committed. + +.. _FoX: https://github.com/mit-crpg/fox .. _xml_interface module: https://github.com/mit-crpg/openmc/blob/develop/src/xml_interface.F90 .. _input_xml module: https://github.com/mit-crpg/openmc/blob/develop/src/input_xml.F90 .. _XML Schema Part 2: http://www.w3.org/TR/xmlschema-2/ .. _boolean: http://www.w3.org/TR/xmlschema-2/#boolean .. _RELAX NG: http://relaxng.org/ .. _compact syntax: http://relaxng.org/compact-tutorial-20030326.html +.. _submodule: http://git-scm.com/book/en/Git-Tools-Submodules