From e76eb525c23c282e56f3ed1532cd8b04ca8fe9bd Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Fri, 24 Feb 2017 20:48:28 +0100 Subject: [PATCH 01/12] skeleton for section of 'code' style for easyconfigs --- docs/Changelog.rst | 1 + docs/Code_style.rst | 64 +++++++++++++++++++++++++++++++++++++++++-- docs/Contributing.rst | 2 ++ docs/conf.py | 2 +- 4 files changed, 66 insertions(+), 3 deletions(-) diff --git a/docs/Changelog.rst b/docs/Changelog.rst index 9658868a..94ac35b1 100644 --- a/docs/Changelog.rst +++ b/docs/Changelog.rst @@ -5,6 +5,7 @@ Changelog for EasyBuild documentation (for EasyBuild release notes, see :ref:`release_notes`) +* **release 20170227.01** (`Feb 27th 2017`): document 'code' :ref:`code_style_easyconfigs` * **release 20170221.01** (`Feb 21st 2017`): add documentation on :ref:`contributing` * **release 20170209.01** (`Feb 9th 2017`): add documentation on implementing easyblocks (see :ref:`implementing_easyblocks`) * **release 20170203.01** (`Feb 3rd 2017`): update release notes for EasyBuild v3.1.0 (see :ref:`release_notes_eb310`) diff --git a/docs/Code_style.rst b/docs/Code_style.rst index a93a7963..cb25d100 100644 --- a/docs/Code_style.rst +++ b/docs/Code_style.rst @@ -21,9 +21,69 @@ The only (major) exception to PEP8 is our preference for longer line lengths: li .. _PEP8: http://www.python.org/dev/peps/pep-0008 +.. _code_style_easyconfigs: -Notes -~~~~~ +Style for easyconfig files +-------------------------- + +We maintain a strict 'code' style for easyconfig files too, which has proved +to be invaluable in making easyconfig files easy to grasp at a glance. + +Major attention points include: + +* :ref:`code_style_easyconfigs_whitespace` +* :ref:`code_style_easyconfigs_indentation` +* :ref:`code_style_easyconfigs_max_line_length` +* :ref:`code_style_easyconfigs_order_grouping` +* :ref:`code_style_easyconfigs_hardcoding` +* :ref:`code_style_easyconfigs_templates_constants` +* :ref:`code_style_easyconfigs_lists` + + +.. _code_style_easyconfigs_whitespace: + +Whitespace +~~~~~~~~~~ + + +.. _code_style_easyconfigs_indentation: + +Indentation +~~~~~~~~~~~ + + +.. _code_style_easyconfigs_max_line_length: + +Maximum line length +~~~~~~~~~~~~~~~~~~~ + + +.. _code_style_easyconfigs_order_grouping: + +Order & grouping of easyconfig parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +.. _code_style_easyconfigs_hardcoding: + +Avoiding hardcoding of parameter values in multiple places +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +.. _code_style_easyconfigs_templates: + +Use of templates & constants +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +.. _code_style_easyconfigs_lists: + +Formatting of lists +~~~~~~~~~~~~~~~~~~~ + + +Links +----- Style guides that go a step beyond PEP8: * http://www.gramps-project.org/wiki/index.php?title=Programming_guidelines diff --git a/docs/Contributing.rst b/docs/Contributing.rst index f62bfb6c..29c3f884 100644 --- a/docs/Contributing.rst +++ b/docs/Contributing.rst @@ -550,6 +550,8 @@ that mostly matches the established PEP8 coding style for Python (since easyconfigs are written in Python syntax). However, also the grouping and ordering of easyconfig parameters is a part of the 'code' style we maintain. +See :ref:`code_style_easyconfigs` for more information. + .. _contributing_review_process_review_pr: diff --git a/docs/conf.py b/docs/conf.py index 6a892cc2..be0a4236 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -43,7 +43,7 @@ # The short X.Y version. version = '3.1.0' # this is meant to reference the version of EasyBuild # The full version, including alpha/beta/rc tags. -release = '20170221.01' # this is meant to reference the version of the documentation itself +release = '20170227.01' # this is meant to reference the version of the documentation itself # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: From e89a87ef6cd326e3676b78ab387e7107fbdd32ef Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Fri, 24 Feb 2017 22:56:11 +0100 Subject: [PATCH 02/12] flesh out subsections on long lines & string quotes in easyconfigs style guide --- docs/Code_style.rst | 83 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 75 insertions(+), 8 deletions(-) diff --git a/docs/Code_style.rst b/docs/Code_style.rst index cb25d100..42ff078f 100644 --- a/docs/Code_style.rst +++ b/docs/Code_style.rst @@ -31,13 +31,45 @@ to be invaluable in making easyconfig files easy to grasp at a glance. Major attention points include: +* :ref:`code_style_easyconfigs_max_line_length` * :ref:`code_style_easyconfigs_whitespace` * :ref:`code_style_easyconfigs_indentation` -* :ref:`code_style_easyconfigs_max_line_length` +* :ref:`code_style_easyconfigs_lists` * :ref:`code_style_easyconfigs_order_grouping` * :ref:`code_style_easyconfigs_hardcoding` * :ref:`code_style_easyconfigs_templates_constants` -* :ref:`code_style_easyconfigs_lists` +* :ref:`code_style_easyconfigs_string_quotes` + + +.. _code_style_easyconfigs_max_line_length: + +Maximum line length +~~~~~~~~~~~~~~~~~~~ + +**Each line should contain no more than 120 characters.** + +If a parameter value is too long line wrapping should be used +or the value should be constructed differently. + +For example, for a long ``description`` value, line wrapping can be used: + +.. code:: python + + description = """A long description with multiple lines, + that wraps around to the next line, and then continues on + to the line after that""" + +For a long value of ``configopts``, string concatenation using '`+=`' can be used. +Do make sure to include a space either and the end of all but the last partial +value, or at the beginning of each partial value except the first one: + +.. code:: python + + configopts = "--first-option --second-option --third-option " + configopts += "--yet-another-option" + +For a parameter value that is a long list, either line wrapping can be used +or each list element can be put on a separate line, see :ref:`code_style_easyconfigs_lists`. .. _code_style_easyconfigs_whitespace: @@ -52,9 +84,9 @@ Indentation ~~~~~~~~~~~ -.. _code_style_easyconfigs_max_line_length: +.. _code_style_easyconfigs_lists: -Maximum line length +Formatting of lists ~~~~~~~~~~~~~~~~~~~ @@ -70,16 +102,51 @@ Avoiding hardcoding of parameter values in multiple places ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. _code_style_easyconfigs_templates: +.. code_style_easyconfigs_templates_constants: Use of templates & constants ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. _code_style_easyconfigs_lists: +.. code_style_easyconfigs_string_quotes: + +Single vs double quotes for string values +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: This is only a recommendation, it is not strictly applied in easyconfig files. + +For string values, the following rules of thumb should be taken into account +with respect to the use of single vs double quotes: + +* use single quotes (`'...'`) for a string representing a single character or 'word' (i.e., a string with no spaces) +* use double quotes (`"..."`) for strings that include one or more spaces +* use triple-quoting (`"""..."""`) for multi-line strings + +These guidelines can be ignored if there is a technical reason for doing so, +for example if double quotes *must* be used to ensure bash expansion of environment variables +(see `buildopts` in the example below). + +For example: + +.. code:: python + + name = 'example' + version = '1.0' + + homepage = 'http://example.com' + description = """A long description with multiple lines, + that wraps around to the next line""" + + toolchain = {'name': 'foss', 'version': '2017a'} + + sources = ['example-v%(version)s.tar.gz'] + + configopts = "--enable-stuff --with-more-stuff" + + buildopts = 'CC="$CC" CFLAGS="$CFLAGS"' + + moduleclass = 'tools' -Formatting of lists -~~~~~~~~~~~~~~~~~~~ Links From 0f18a6d89d9b96f10e8ccb7261e1e9c3749c1bfb Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Fri, 24 Feb 2017 23:11:25 +0100 Subject: [PATCH 03/12] fix formatting, change title for easyconfigs style guide --- docs/Code_style.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/Code_style.rst b/docs/Code_style.rst index 42ff078f..5208b8ef 100644 --- a/docs/Code_style.rst +++ b/docs/Code_style.rst @@ -23,8 +23,8 @@ The only (major) exception to PEP8 is our preference for longer line lengths: li .. _code_style_easyconfigs: -Style for easyconfig files --------------------------- +Easyconfigs style guide +----------------------- We maintain a strict 'code' style for easyconfig files too, which has proved to be invaluable in making easyconfig files easy to grasp at a glance. @@ -118,9 +118,9 @@ Single vs double quotes for string values For string values, the following rules of thumb should be taken into account with respect to the use of single vs double quotes: -* use single quotes (`'...'`) for a string representing a single character or 'word' (i.e., a string with no spaces) -* use double quotes (`"..."`) for strings that include one or more spaces -* use triple-quoting (`"""..."""`) for multi-line strings +* use single quotes (``'...'``) for a string representing a single character or 'word' (i.e., a string with no spaces) +* use double quotes (```"..."``) for strings that include one or more spaces +* use triple-quoting (``"""..."""``) for multi-line strings These guidelines can be ignored if there is a technical reason for doing so, for example if double quotes *must* be used to ensure bash expansion of environment variables From 63aa157e13c2d87c5b25013bf2f8234946f185b1 Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Fri, 24 Feb 2017 23:23:19 +0100 Subject: [PATCH 04/12] fix typo --- docs/Code_style.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Code_style.rst b/docs/Code_style.rst index 5208b8ef..02720919 100644 --- a/docs/Code_style.rst +++ b/docs/Code_style.rst @@ -119,7 +119,7 @@ For string values, the following rules of thumb should be taken into account with respect to the use of single vs double quotes: * use single quotes (``'...'``) for a string representing a single character or 'word' (i.e., a string with no spaces) -* use double quotes (```"..."``) for strings that include one or more spaces +* use double quotes (``"..."``) for strings that include one or more spaces * use triple-quoting (``"""..."""``) for multi-line strings These guidelines can be ignored if there is a technical reason for doing so, From 23ea1d0ee2c5f41f62136ded1e9c3074632071d3 Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Mon, 27 Feb 2017 09:37:27 +0100 Subject: [PATCH 05/12] flesh out section on whitespace in easyconfigs --- docs/Code_style.rst | 39 ++++++++++++++++++++++++++++++--------- 1 file changed, 30 insertions(+), 9 deletions(-) diff --git a/docs/Code_style.rst b/docs/Code_style.rst index 02720919..f5b531d1 100644 --- a/docs/Code_style.rst +++ b/docs/Code_style.rst @@ -46,7 +46,7 @@ Major attention points include: Maximum line length ~~~~~~~~~~~~~~~~~~~ -**Each line should contain no more than 120 characters.** +**Each line must contain no more than 120 characters.** If a parameter value is too long line wrapping should be used or the value should be constructed differently. @@ -59,7 +59,7 @@ For example, for a long ``description`` value, line wrapping can be used: that wraps around to the next line, and then continues on to the line after that""" -For a long value of ``configopts``, string concatenation using '`+=`' can be used. +For a long value of ``configopts``, string concatenation using '``+=```' can be used. Do make sure to include a space either and the end of all but the last partial value, or at the beginning of each partial value except the first one: @@ -77,6 +77,27 @@ or each list element can be put on a separate line, see :ref:`code_style_easycon Whitespace ~~~~~~~~~~ +Whitespace (i.e., spaces, tabs and newlines) is an integral part of Python syntax, +and hence very important. + +In easyconfigs specifically, all **parameter definitions must be left-aligned**, +i.e., no whitespace to the left of the names of the parameters being defined +is allowed. Not honoring this rule will result in ``SyntaxError``'s. + +On top of that, a couple of additional whitespace style rules must be taken into account: + +* **tab characters can not be used for indentation** + + * each tab character must be replaced with *exactly 4 spaces* + * see also :ref:`code_style_easyconfigs_indentation` + +* **blank lines must be empty** (no whitespace characters included) +* **no multiple blank lines in a row** +* **no trailing whitespace**, i.e., no extra spaces/tabs at the end of lines + +In addition, blank lines must be used to separate groups of parameter definition +(see :ref:`code_style_easyconfigs_order_grouping`) and to aid with readability. + .. _code_style_easyconfigs_indentation: @@ -102,29 +123,29 @@ Avoiding hardcoding of parameter values in multiple places ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code_style_easyconfigs_templates_constants: +.. _code_style_easyconfigs_templates_constants: Use of templates & constants ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code_style_easyconfigs_string_quotes: +.. _code_style_easyconfigs_string_quotes: -Single vs double quotes for string values +Single or double quotes for string values ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: This is only a recommendation, it is not strictly applied in easyconfig files. For string values, the following rules of thumb should be taken into account -with respect to the use of single vs double quotes: +with respect to the use of single or double quotes: -* use single quotes (``'...'``) for a string representing a single character or 'word' (i.e., a string with no spaces) +* use single quotes (``'...'``) for strings representing a single character or 'word' (i.e., a string with no spaces) * use double quotes (``"..."``) for strings that include one or more spaces * use triple-quoting (``"""..."""``) for multi-line strings These guidelines can be ignored if there is a technical reason for doing so, for example if double quotes *must* be used to ensure bash expansion of environment variables -(see `buildopts` in the example below). +(see ``buildopts`` in the example below). For example: @@ -141,7 +162,7 @@ For example: sources = ['example-v%(version)s.tar.gz'] - configopts = "--enable-stuff --with-more-stuff" + configopts = "--enable-stuff --with-more-stuff --disable-other-stuff" buildopts = 'CC="$CC" CFLAGS="$CFLAGS"' From 29a15dfec0297c204fd05d47f0952f0e872b2b9d Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Wed, 8 Mar 2017 07:47:20 +0100 Subject: [PATCH 06/12] flesh out subsection on indentation in easyconfigs style guide, mention --check-style, add (empty) subsection on easyconfig file names --- docs/Code_style.rst | 68 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 63 insertions(+), 5 deletions(-) diff --git a/docs/Code_style.rst b/docs/Code_style.rst index f5b531d1..a426d5d4 100644 --- a/docs/Code_style.rst +++ b/docs/Code_style.rst @@ -39,6 +39,9 @@ Major attention points include: * :ref:`code_style_easyconfigs_hardcoding` * :ref:`code_style_easyconfigs_templates_constants` * :ref:`code_style_easyconfigs_string_quotes` +* :ref:`code_style_easyconfigs_file_names` + +.. note:: You can check whether easyconfigs adhere to the easyconfig style rules using ``eb --check-style``. .. _code_style_easyconfigs_max_line_length: @@ -59,6 +62,9 @@ For example, for a long ``description`` value, line wrapping can be used: that wraps around to the next line, and then continues on to the line after that""" +Usually, a single leading space is used on continuation lines for descriptions +that are wrapped across multiple lines. + For a long value of ``configopts``, string concatenation using '``+=```' can be used. Do make sure to include a space either and the end of all but the last partial value, or at the beginning of each partial value except the first one: @@ -77,7 +83,7 @@ or each list element can be put on a separate line, see :ref:`code_style_easycon Whitespace ~~~~~~~~~~ -Whitespace (i.e., spaces, tabs and newlines) is an integral part of Python syntax, +Whitespace (i.e., spaces, tabs) is an integral part of Python syntax, and hence very important. In easyconfigs specifically, all **parameter definitions must be left-aligned**, @@ -86,16 +92,19 @@ is allowed. Not honoring this rule will result in ``SyntaxError``'s. On top of that, a couple of additional whitespace style rules must be taken into account: -* **tab characters can not be used for indentation** +* **no tab characters used for indentation** - * each tab character must be replaced with *exactly 4 spaces* + * each tab must be replaced with *exactly 4 spaces* * see also :ref:`code_style_easyconfigs_indentation` -* **blank lines must be empty** (no whitespace characters included) +* **no whitespace on blank lines** * **no multiple blank lines in a row** * **no trailing whitespace**, i.e., no extra spaces/tabs at the end of lines +* **a single space must be included before and after an assignment operator** '``=``' +* **a single space must be included (only) after commas** ``,`` **and colons** ``:`` (*not* before) +* **no spaces directly after** ``(``, ``[`` **or** ``{`, **nor before** ``)``, ``]`` **or** ``}`` characters -In addition, blank lines must be used to separate groups of parameter definition +In addition, a single blank line must be used to separate groups of parameter definitions (see :ref:`code_style_easyconfigs_order_grouping`) and to aid with readability. @@ -104,6 +113,50 @@ In addition, blank lines must be used to separate groups of parameter definition Indentation ~~~~~~~~~~~ +**Indentation must be used for list or dictionary parameter values that +are spread across multiple lines.** + +Each indentation level corresponds to exactly 4 spaces; *do not use +tab characters for indentation* (see :ref:`code_style_easyconfigs_whitespace`). + +For long lists, you can either put each list element on a new line and +indent with (exactly) 4 spaces, +or simply break the list across multiple lines while aligning the first list element on +each line. + +Which formatting style you should for lists use depends on the length of the individual +list elements and the length of the entire list: + +* short elements suggest simply breaking the list across multiple lines; +* long elements suggest one list element per line; +* long lists suggest avoiding a single element per line, to avoid consuming a lot of vertical space + +In addition, a single list element per line allows for including comments for particular list elements. + +With the above in mind it is difficult to prescribe strict rules for picking a formatting style for lists, +so you will need to pick one yourself (taking into account :ref:`code_style_easyconfigs_max_line_length`). + +For dictionary values, it is custom to put each key-value pair on a separate line, +and to indent each line using exactly 4 spaces. + +For example: + +.. code:: python + + sources = [SOURCE_TAR_GZ] + + # example of list value spread across multiple lines with one element per line + patches = [ + 'fix-compilation.patch', # patch to fix compilation problem + 'backport-bugfix.patch', # patch to backport bug fix to this version + ] + + # example of list value spread across multiple lines by breaking the list + sanity_check_paths = { + 'files': ['bin/example1', 'bin/example2', 'bin/example3', 'bin/example4', + 'lib/libexample1.a', 'lib/libexample2.a'], + 'dirs': ['example_directory'], + } .. _code_style_easyconfigs_lists: @@ -169,6 +222,11 @@ For example: moduleclass = 'tools' +.. _code_style_easyconfigs_file_names: + +Easyconfig file names +~~~~~~~~~~~~~~~~~~~~~ + Links ----- From f1442ca0081e75dc9e28f7cdefa7a98fa2369fea Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Fri, 10 Mar 2017 09:54:02 +0100 Subject: [PATCH 07/12] flesh out section on order/grouping of parameters --- docs/Code_style.rst | 83 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 74 insertions(+), 9 deletions(-) diff --git a/docs/Code_style.rst b/docs/Code_style.rst index a426d5d4..8f988deb 100644 --- a/docs/Code_style.rst +++ b/docs/Code_style.rst @@ -34,7 +34,6 @@ Major attention points include: * :ref:`code_style_easyconfigs_max_line_length` * :ref:`code_style_easyconfigs_whitespace` * :ref:`code_style_easyconfigs_indentation` -* :ref:`code_style_easyconfigs_lists` * :ref:`code_style_easyconfigs_order_grouping` * :ref:`code_style_easyconfigs_hardcoding` * :ref:`code_style_easyconfigs_templates_constants` @@ -110,10 +109,10 @@ In addition, a single blank line must be used to separate groups of parameter de .. _code_style_easyconfigs_indentation: -Indentation -~~~~~~~~~~~ +Indentation for list and dictionary values +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**Indentation must be used for list or dictionary parameter values that +**Indentation must be used for list and dictionary parameter values that are spread across multiple lines.** Each indentation level corresponds to exactly 4 spaces; *do not use @@ -158,17 +157,83 @@ For example: 'dirs': ['example_directory'], } -.. _code_style_easyconfigs_lists: - -Formatting of lists -~~~~~~~~~~~~~~~~~~~ - .. _code_style_easyconfigs_order_grouping: Order & grouping of easyconfig parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Parameter definitions must be ordered and organised in groups consistently across easyconfig files.** + +Even though the order of the parameter definitions in easyconfig files (mostly) doesn't matter, +maintaining a consistent order across easyconfig files helps to make them easier to digest at a glance. + +Related easyconfig parameters must grouped together, with a (single) blank included between groups of parameters. + +.. note:: Order only matters when a particular parameter definition is (partially) defined in terms of another + parameter, for example when ``version`` is used to define one of the values in ``sources``. + + This only applies to definitions that use the ``%`` operator rather than an equivalent template + like ``%(version)s``. + +Parameter definitions in easyconfig files must be ordered/groups according to the following rules: + +* if the ``easyblock`` parameter is defined it must be listed first, followed by a blank line; + +* ``name`` and ``version`` must be next, in that order, grouped together and followed by a blank line; + +* ``homepage`` and ``description`` are next, in that order, grouped together and followed by a blank line; + +* ``toolchain`` must be next, optionally followed by ``toolchainopts`` (if defined), followed by a blank line; + +* ``sources`` must be next (if defined), followed by a blank line; + if ``source_urls`` is defined, it must be included right before ``sources`` (in the same group); + +* defined parameters that influence particular steps of the build and installation procedure must be included in order, + i.e., ``(pre)configopts`` must be included before ``(pre)buildopts``, which must be included before ``(pre)installopts``, etc.; + +* ``sanity_check_paths`` and ``sanity_check_commands`` must be included towards the end of the easyconfig file, + if they are defined; + +* parameters influencing the contents of the generated module file (e.g., ``modextrapaths``, ``modextravars``, ...) + must be included *after* the ``sanity_check_*`` parameters, if they are defined + +* ``moduleclass`` must be included as the last line + +Example:: + +.. code:: python + + # optional example header + + easyblock = 'ConfigureMake' + + name = 'example' + version = '1.2.3' + + homepage = 'http://example.com' + description = "Example description" + + toolchain = {'name': 'dummy', 'version': ''} + toolchainopts = {'pic': True} # note: optional + + source_urls = ['http://example.com'] + sources = [SOURCE_TAR_GZ] + + configopts = '--with-foo' + + prebuildopts = 'export COMPILER_FLAGS="$CFLAGS" && ' + buildopts = 'CC="$CC"' + + sanity_check_paths = { + 'files': ['example'], + 'dirs': [], + } + + modextrapaths = {'PATH': ''} + + moduleclass = '' + .. _code_style_easyconfigs_hardcoding: From 1ba29676d52e0f8abc8859bbfca60a154ed81e53 Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Fri, 10 Mar 2017 10:17:47 +0100 Subject: [PATCH 08/12] fix formatting problem --- docs/Code_style.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Code_style.rst b/docs/Code_style.rst index 8f988deb..759175c7 100644 --- a/docs/Code_style.rst +++ b/docs/Code_style.rst @@ -200,7 +200,7 @@ Parameter definitions in easyconfig files must be ordered/groups according to th * ``moduleclass`` must be included as the last line -Example:: +Example: .. code:: python @@ -215,7 +215,7 @@ Example:: description = "Example description" toolchain = {'name': 'dummy', 'version': ''} - toolchainopts = {'pic': True} # note: optional + toolchainopts = {'pic': True} source_urls = ['http://example.com'] sources = [SOURCE_TAR_GZ] From b337525aa29305c502306c03e9effc5bc1c71dd8 Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Mon, 20 Mar 2017 09:19:56 +0100 Subject: [PATCH 09/12] minor additions to order/group subsection in easyconfigs style guide --- docs/Code_style.rst | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/Code_style.rst b/docs/Code_style.rst index 759175c7..b22674ad 100644 --- a/docs/Code_style.rst +++ b/docs/Code_style.rst @@ -187,10 +187,16 @@ Parameter definitions in easyconfig files must be ordered/groups according to th * ``toolchain`` must be next, optionally followed by ``toolchainopts`` (if defined), followed by a blank line; * ``sources`` must be next (if defined), followed by a blank line; - if ``source_urls`` is defined, it must be included right before ``sources`` (in the same group); -* defined parameters that influence particular steps of the build and installation procedure must be included in order, - i.e., ``(pre)configopts`` must be included before ``(pre)buildopts``, which must be included before ``(pre)installopts``, etc.; + * if ``source_urls`` is defined, it must be included right *before* ``sources`` (in the same group); + * if ``patches`` or ``checksums`` are defined, they must be included right *after* ``sources``, in that order (and in the same group); + +* if ``builddependencies``, ``dependencies`` or ``osdependencies`` are defined they must be included next, grouped together; + +* defined parameters that influence particular steps of the build and installation procedure must be included in order + and after the parameters mentioned above; + + * i.e., ``(pre)configopts`` must be included before ``(pre)buildopts``, which must be included before ``(pre)installopts``, etc.; * ``sanity_check_paths`` and ``sanity_check_commands`` must be included towards the end of the easyconfig file, if they are defined; @@ -219,6 +225,7 @@ Example: source_urls = ['http://example.com'] sources = [SOURCE_TAR_GZ] + checksums = ['41150b03ec5b7f5a49390cc10eeb96d5'] configopts = '--with-foo' From 7aa636bcfee64c8c594a5a6650135541905f74a6 Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Mon, 20 Mar 2017 09:29:08 +0100 Subject: [PATCH 10/12] flesh out easyconfigs style guide subsection on template values --- docs/Code_style.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/Code_style.rst b/docs/Code_style.rst index b22674ad..6f10988c 100644 --- a/docs/Code_style.rst +++ b/docs/Code_style.rst @@ -247,6 +247,29 @@ Example: Avoiding hardcoding of parameter values in multiple places ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Hardcoding of parameter values in multiple places must be avoided if possible, +the available easyconfig templates must be used instead (see :ref:`avail_easyconfig_templates`). + +For example, rather than hardcoding the software version in both the ``version`` and ``sources`` +parameter definitions, the ``%(version)s`` template value should be used instead: + +.. code:: python + + name = 'example' + version = '1.2.3' + ... + sources = ['%(name)s-v%(version)s.tar.gz'] + +Commonly used templates include: + +* ``%(namelower)s`` for the lower-case software name +* ``%(version)s`` for the full software version +* ``%(version_major)s``, ``%(version_minor)s``, ``%(version_major_minor)s`` for partial software versions +* ``SOURCE_TAR_GZ``, ``SOURCE_TGZ``, etc. for the ``sources`` parameter +* ``GNU_SOURCE``, ``PYPI_SOURCE``, ``SOURCEFORGE_SOURCE``, etc. for the ``source_urls`` parameter +* ``%(pyver)s`` and ``%(pyshortver)s`` for the (partial) Python version +* ``%(installdir)s`` for the software installation prefix +* ``SHLIB_EXT`` for the extension of shared libraries .. _code_style_easyconfigs_templates_constants: From b28133536d5ff440d8beb796af1f4794d4a1c968 Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Mon, 20 Mar 2017 10:10:29 +0100 Subject: [PATCH 11/12] minor enhancements to easyconfigs style guide subsection on templates --- docs/Code_style.rst | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/docs/Code_style.rst b/docs/Code_style.rst index 6f10988c..26a76210 100644 --- a/docs/Code_style.rst +++ b/docs/Code_style.rst @@ -242,13 +242,13 @@ Example: moduleclass = '' -.. _code_style_easyconfigs_hardcoding: +.. _code_style_easyconfigs_templates_constants: -Avoiding hardcoding of parameter values in multiple places -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Use of templates rather than hardcoding parameter values +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Hardcoding of parameter values in multiple places must be avoided if possible, -the available easyconfig templates must be used instead (see :ref:`avail_easyconfig_templates`). +the available easyconfig templates ``%(...)s`` must be used instead (see :ref:`avail_easyconfig_templates`). For example, rather than hardcoding the software version in both the ``version`` and ``sources`` parameter definitions, the ``%(version)s`` template value should be used instead: @@ -271,11 +271,6 @@ Commonly used templates include: * ``%(installdir)s`` for the software installation prefix * ``SHLIB_EXT`` for the extension of shared libraries -.. _code_style_easyconfigs_templates_constants: - -Use of templates & constants -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. _code_style_easyconfigs_string_quotes: From fc0464d1154894cc5dd31badc9e25d14e7e8a6b1 Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Mon, 20 Mar 2017 10:16:10 +0100 Subject: [PATCH 12/12] complete easyconfigs style guide with subsection on easyconfig filenames --- docs/Code_style.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/Code_style.rst b/docs/Code_style.rst index 26a76210..67feb294 100644 --- a/docs/Code_style.rst +++ b/docs/Code_style.rst @@ -247,7 +247,7 @@ Example: Use of templates rather than hardcoding parameter values ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Hardcoding of parameter values in multiple places must be avoided if possible, +**Hardcoding of parameter values in multiple places must be avoided if possible**, the available easyconfig templates ``%(...)s`` must be used instead (see :ref:`avail_easyconfig_templates`). For example, rather than hardcoding the software version in both the ``version`` and ``sources`` @@ -317,6 +317,11 @@ For example: Easyconfig file names ~~~~~~~~~~~~~~~~~~~~~ +**Easyconfig filenames must follow the pattern** ``-[-][].eb``. + +The ``toolchain`` part is omitted when the ``dummy`` toolchain is used; the ``versionsuffix`` part is omitted when the ``versionsuffix`` is empty. + +This is strictly enforced because the 'robot' dependency resolution mechanism relies on easyconfig filenames, see also :ref:`robot_search_path`. Links -----