jxy / Examples

LaTeX Examples Document Source

This is the OpenMP Examples document in LaTeX format.
Please see the master file, openmp-examples.tex, for more information.

For a brief revision history, please see Changes.log.

For copyright information, please see omp_copyright.txt.


1) Process for adding an example

   - Prepare source code and text description
   - Give a high level description in a trac ticket
   - Determine a name (ename) for the example
      - Propose a new name if creating a new chapter
      - Use the existing name if adding to an existing chapter
   - Number the example within the chapter (seq-no)
   - Create files for the source code with proper tags in
      sources/Example_<ename>.<seq-no>c.c
      sources/Example_<ename>.<seq-no>f.f
   - Create or update the description text in the chapter file
      Examples_<ename>,tex
   - If needed, add the new chapter file name in 
      Makefile
      openmp-examples.tex
   - Commit the changes in git and push to the GitHub repo
   - Discuss and vote in committee

2) Tags (meta data) for example sources

  @@name:        <ename>.<seq-no>[c|cpp|f|f90]
  @@type:        C|C++|F-fixed|F-free
  @@compilable:  yes|no|maybe
  @@linkable:    yes|no|maybe
  @@expect:      success|failure|nothing|rt-error
  @@version:     omp_<verno>

  "name" is the name of an example
  "type" is the source code type, which can be translated into or from
          proper file extension (c,cpp,f,f90)
  "compilable" indicates whether the source code is compilable
  "linkable" indicates whether the source code is linkable
  "expect" indicates some expected result for testing purpose
          "success|failure|nothing" applies to the result of code compilation
          "rt-error" is for a case where compilation may be successful, 
          but the code contains potential runtime issues (such as race condition).
          Alternative would be to just use "conforming" or "non-conforming".
  "version" indicates features for a specific OpenMP version, such as "omp_5.0"

3) LaTeX macros for examples

- Source code with language h-rules
   \cexample[<verno>]{<ename>}{<seq-no>}     % for C/C++ examples
   \cppexample[<verno>]{<ename>}{<seq-no>}   % for C++ examples
   \fexample[<verno>]{<ename>}{<seq-no>}     % for fixed-form Fortran examples
   \ffreeexample[<verno>]{<ename>}{<seq-no>} % for free-form Fortran examples

- Source code without language h-rules
   \cnexample[<verno>]{<ename>}{<seq-no>}
   \cppnexample[<verno>]{<ename>}{<seq-no>}
   \fnexample[<verno>]{<ename>}{<seq-no>}
   \ffreenexample[<verno>]{<ename>}{<seq-no>}

   Optional <verno> can be supplied in a macro to include a specific OpenMP
   version in the example header.  This option also suggests one additional
   tag (@@version) line is included in the corresponding source code. 
   If this is not the case (i.e., no @@version tag line), one needs to 
   prefix <verno> with an underscore '_' symbol in the macro.

- Language h-rules
   \cspecificstart, \cspecificend
   \cppspecificstart, \cppspecificend
   \ccppspecificstart, \ccppspecificend
   \fortranspecificstart, \fortranspecificend

- See openmp.sty for more information