Merge pull request #165 from Caylo/yeb-docs

yeb docs update

Author: boegel

docs/Writing_yeb_easyconfig_files.rst

@@ -117,6 +117,20 @@ elsewhere too) can be done as follows::
     versionsuffix: !join [-Python-, *pyver]
 
 
+.. _easyconfig_yeb_format_syntax_escaping:
+
+Escaping string values with single or double quotes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Strings in YAML can be unquoted. However, when they contain special characters they need to be escaped by either single-
+or double-quoting the string.
+
+Special characters that require single quotes are: `:` `{` `}` `[` `]` `,` `&` `*` `#` `?` `|` `-` `<` `>` `=` `!` `%` `@` and `\``.
+When using single-quoted strings, any single quote inside the string must be doubled to escape it.
+
+If the string contains control characters such as `\n`, it must be escaped with double quotes. 
+
+
 .. _easyconfig_yeb_format_syntax_easyconfig_parameters:
 
 Easyconfig parameter values
@@ -138,6 +152,7 @@ Using scalar values is straight-forward, no special syntax is required.
 
 For string values, no quotes must be used (in general).
 However, quotes are sometimes required to escape characters that have special meaning in YAML (like '``:``').
+(Also see: :ref:`easyconfig_yeb_format_syntax_escaping`)
 It's worth noting that there's a subtle difference between using single and double quotes, see
 `Flow Scalar Styles <http://www.yaml.org/spec/1.2/spec.html#id2786942>`_.
 
@@ -211,9 +226,9 @@ For example, sequence values can be used in a mapping::
 
 And sequences of sequences are also supported::
 
-    dependencies:
-        - [bzip2, 1.0.6]
-        - [Python, 2.7.10]
+    osdependencies
+        - zlib
+        - [openssl-devel, libssl-dev, libopenssl-devel]
 
 
 .. _easyconfig_yeb_format_syntax_template_values_constants:
@@ -238,19 +253,27 @@ See also :ref:`easyconfig_param_templates`.
 Dependencies
 ~~~~~~~~~~~~
 
-The list of (build) dependencies can be specified as list of lists, see also
-:ref:`easyconfig_yeb_format_syntax_nesting`.
+We updated the way dependencies are specified to match with the new toolchain format (:ref:`easyconfig_yeb_format_new`)
+The format is a bit more verbose than before, but easier to read. Each dependency is a list entry, indicated by a dash
+and space (`- `). Each entry can specify a ``name: version`` key-value pair, and a ``versionsuffix`` and ``toolchain``.
+Only the ``name: version`` pair is required.
+
+Dependencies can also be external modules. In this case, the dependency has to be specified with a ``name`` and the marker 
+``external_module: True``. The boolean value is not case-sensitive.
+
 
 A straightforward example::
 
-    dependencies: [
-        [libreadline, 6.3],
-        [Tcl, 8.6.4],
-    ]
-    builddependencies: [
+    dependencies:
+        - libreadline: 6.3
+        - Tcl: 8.6.4
+        - name: fftw/3.3.4.4
+          external_module: True
+
+    builddependencies:
         # empty versionsuffix, different toolchain (GCC/4.9.2)
-        [CMake, 3.2.2, '', [GCC, 4.9.2],
-    ]
+        - CMake: 3.2.2
+          toolchain: GCC, 4.9.2
 
 A more complicated example from a toolchain easyconfig, where also the ``!join`` operator
 (see :ref:`easyconfig_yeb_format_syntax_string_concatenation`) and internal variables
@@ -268,17 +291,69 @@ A more complicated example from a toolchain easyconfig, where also the ``!join``
 
         - &comp_mpi_tc [gompi, 1.4.10]
 
-    dependencies: [
-        *comp,
-        [OpenMPI, 1.6.4, '', *comp],
-        [*blaslib, *blasver, *blas_suff, *comp_mpi_tc],
-        [FFTW, 3.3.3, '', *comp_mpi_tc],
-        [ScaLAPACK, 2.0.2, !join [-, *blas, *blas_suff], *comp_mpi_tc]
-    ]
+    dependencies:
+        - *comp_name: *comp_version
+        - OpenMPI: 1.6.4
+          toolchain: *comp
+        - *blaslib: *blasver
+          versionsuffix: *blas_suff
+          toolchain: *comp_mpi_tc
+        - FFTW: 3.3.3
+          toolchain: *comp_mpi_tc
+        - ScaLAPACK: 2.0.2
+          versionsuffix: !join [-, *blas, *blas_suff]
+          toolchain: *comp_mpi_tc
 
 For the full version of this easyconfig file, see the example ``.yeb`` easyconfig
 :ref:`easyconfig_yeb_format_examples_goolf1410`.
 
+.. _easyconfig_yeb_format_new:
+
+OS dependencies and sanity check paths
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To specify parameters that used to contain tuples such as ``osdependencies`` and ``sanity_check_paths``, simply use
+lists (sequences) instead of tuples.
+
+For example::
+
+    # note: this is eb syntax, will not work in .yeb files
+    osdependencies = [('openssl-devel', 'libssl-dev', 'libopenssl-devel')]
+
+Becomes::
+
+    osdependencies: [[openssl-devel, libssl-dev, libopenssl-devel]] 
+
+And::
+
+    # note: this is eb syntax, will not work in .yeb files
+    sanity_check_paths = {
+        'files': ['fileA', ('fileB', 'fileC')],
+        'dirs' : ['dirA', 'dirB'],
+    }
+
+Becomes::
+
+    sanity_check_paths: {
+        files: [fileA, [fileB, fileC]],
+        dirs: [dirA, dirB]
+    }
+
+Shorthands for common easyconfig parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Toolchain format
+################
+
+The easyconfig parameter ``toolchain`` in .eb files is defined as a dictionary ``{'name':'foo', 'version':'bar'}``. In
+the .yeb format, this can be done much easier by just using ``name, version``. E.g::
+
+    # note: this is eb syntax, will not work in yeb files
+    toolchain = {'name':'intel', 'version':'2015b'}
+
+becomes::
+
+    toolchain: intel, 2015b
 
 .. _easyconfig_yeb_format_examples:
 
@@ -306,7 +381,7 @@ Example easyconfig for gzip v1.6 using the ``GCC/4.9.2`` toolchain.
         gzip is a popular data compression program
         as a replacement for compress
 
-    toolchain: {name: GCC, version: 4.9.2}
+    toolchain: GCC, 4.9.2
 
     # http://ftp.gnu.org/gnu/gzip/gzip-1.6.tar.gz
     source_urls: [*GNU_SOURCE]
@@ -359,13 +434,18 @@ Easyconfig file in YAML syntax for the goolf v1.4.10 toolchain.
     # compiler toolchain dependencies
     # we need GCC and OpenMPI as explicit dependencies instead of gompi toolchain
     # because of toolchain preperation functions
-    dependencies: [
-        *comp,
-        [OpenMPI, 1.6.4, '', *comp],
-        [*blaslib, *blasver, *blas_suff, *comp_mpi_tc],
-        [FFTW, 3.3.3, '', *comp_mpi_tc],
-        [ScaLAPACK, 2.0.2, !join [-, *blas, *blas_suff], *comp_mpi_tc]
-    ]
+        dependencies:
+            - *comp_name: *comp_version
+            - OpenMPI: 1.6.4
+              toolchain: *comp
+            - *blaslib: *blasver
+              versionsuffix: *blas_suff
+              toolchain: *comp_mpi_tc
+            - FFTW: 3.3.3
+              toolchain: *comp_mpi_tc
+            - ScaLAPACK: 2.0.2
+              versionsuffix: !join [-, *blas, *blas_suff]
+              toolchain: *comp_mpi_tc
 
     moduleclass: toolchain
 
@@ -390,22 +470,24 @@ Python-2.7.10-intel-2015b.yeb
         Python is a programming language that lets you work more quickly and integrate your systems
         more effectively.
 
-    toolchain: {name: intel, version: 2015b}
+    toolchain: intel, 2015b
     toolchainopts: {pic: True, opt: True, optarch: True}
 
     source_urls: ['http://www.python.org/ftp/python/%(version)s/']
     sources: [*SOURCE_TGZ]
 
     # python needs bzip2 to build the bz2 package
     dependencies: [
-        [bzip2, 1.0.6],
-        [zlib, 1.2.8],
-        [libreadline, '6.3'],
-        [ncurses, '5.9'],
-        [SQLite, 3.8.10.2],
-        [Tk, 8.6.4, -no-X11],
-    #   [OpenSSL, 1.0.1m],  # OS dependency should be preferred if the os version is more recent then this version, its
-    #   nice to have an up to date openssl for security reasons
+        - bzip2: 1.0.6
+        - zlib: 1.2.8
+        - libreadline: 6.3
+        - ncurses: 5.9
+        - SQLite: 3.8.10.2
+        - Tk: 8.4.6
+          versionsuffix: -no-X11
+      # - OpenSSL: 1.0.1m
+      #   OS dependency should be preferred if the os version is more recent then this version, its
+      #   nice to have an up to date openssl for security reasons
     ]
 
     osdependencies: [[openssl-devel, libssl-dev, libopenssl-devel]]