Merge pull request #1742 from jedwards4b/adding_components

Adding components

doc/source/users_guide/adding-cases.rst

@@ -151,7 +151,3 @@ The steps for adding a new component grid to the model system follow. gain, this
       Test the new grid with CAM(newgrid), CLM(newgrid), DOCN(gx1v6), DICE(gx1v6)
       (write an example)
 
-===================
-Adding components
-===================
-

doc/source/users_guide/adding-components.rst

@@ -0,0 +1,36 @@
+.. _adding-components:
+
+===================
+Adding components
+===================
+
+Here are the steps to add prognostic components to CIME models.  
+
+There are a couple of aspects of a component interface to CIME, the
+scripts interface which controls setting up component inputs and
+building the component and the run interface which controls connecting
+the component to the coupler and through the coupler, the other
+components of the CIME based model.
+
+The component should have a subdirectory **cime_config** and this
+subdirectory should have two files **buildnml** and **buildlib** The
+**buildnml** script is used to build the components instructional,
+runtime inputs.  These have traditionally been in the form of fortran
+namelists but may also follow other formats.  The **buildnml** may
+either be called from the command line or as a python subroutine.  If
+buildnml is called from the command line it will be passed the
+caseroot directory on the command line.  If it is called as a
+subroutine, the subroutine name must be buildnml and it will take
+three arguments, a Case object, a caseroot directory and a component
+name.  The **buildlib** script will always be called from the command
+line, it is called in the case.build step and is expected to build the
+the buildlib script will be called with three arguments in order they
+are caseroot, libroot (the location of the installed library,
+typically EXEROOT/lib) and bldroot, the location of the component
+build directory.  Look at the cime internal components such as datm
+for an example.
+
+The coupler interface is dependent on which coupler is used, for the mct coupler in cime
+the component model must provide NNN_INIT_MCT, NNN_RUN_MCT, NNN_FINAL_MCT where NNN is the
+component type of the particular component (eg ATM for an atmosphere, LND for a land model)
+these subroutines are expected to be in the component library.

doc/source/users_guide/index.rst

@@ -43,6 +43,8 @@ CIME User's Guide Part 2: CIME internals, Porting, Testing and Use Cases
    multi-instance.rst
    adding-cases.rst
    use_cases/use-cases.rst
+   adding-components.rst
+   faq/faq.rst
 
 Indices and tables
 ==================