DRAFT mcf: Move config file format description out of weboslayers.py (v7.1.1)

- Update to document McfFileVersion 2.

- Clarify the semantics of the "fetch" item

- Also tweak various other portions of the commentary.

files/weboslayers.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2008-2018 LG Electronics, Inc.
+# Copyright (c) 2008-2019 LG Electronics, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -11,52 +11,19 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-#
-# This implementation introduces next generation build environment for
-# Open webOS. The change introduces a mechanism to add additional layers to the
-# base ones: oe-core, meta-oe, and meta-webos, and to specify the commits to be
-# used for each. mcf now expects the layers to be defined in this file
-# (weboslayers.py in the same directory as mcf) as a list of Python data tuples:
-#
-# webos_layers = [
-# ('layer-name', priority, 'URL', 'submission', 'working-dir'),
-# ...
-# ]
-#
-# where:
-#
-# layer-name  = Unique identifier; it represents the layer directory containing
-#               conf/layer.conf.
-#
-# priority    = Integer layer priority as defined by OpenEmbedded. It also
-#               specifies the order in which layers are searched for files.
-#               Larger values have higher priority. A value of -1 indicates
-#               that the entry is not a layer; for example, bitbake.
-#
-# URL         = The Git repository address for the layer from which to clone.
-#               A value of '' skips the cloning.
-#
-# submission  = The information used by Git to checkout and identify the precise
-#               content. Submission values could be "branch=<name>" and
-#               "commit=<id>" or "tag=<tag>". Omitted branch information means
-#               only that "master" will be used as the name of the local
-#               branch. Omitted commit or tag means origin/HEAD will be checked
-#               out (which might NOT be origin/master, although
-#               it usually is).
-#
-# working-dir = Alternative directory for the layer.
-#
-# The name of the distribution is also defined in this file
-# along with a list of the valid MACHINE-s
-#
 
+# Value for DISTRO
 Distribution = "webos"
 
 # Supported MACHINE-s
 Machines = ['raspberrypi3','qemux86']
 
-# github.com/openembedded repositories are read-only mirrors of the authoritative
-# repositories on git.openembedded.org
+# webos_layers = [
+# ('layer-name', priority, 'URL', 'submission', 'working-dir'),
+# ...
+# ]
+# Note that the github.com/openembedded repositories are read-only mirrors of
+# the authoritative repositories on git.openembedded.org .
 webos_layers = [
 ('bitbake',                   -1, 'git://github.com/openembedded/bitbake.git',              'branch=1.32,commit=0193e1f', ''),
 

scripts/mcf

@@ -13,6 +13,51 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
+# The configuration file that "mcf" reads specifies the name of the distribution, the supported MACHINE-s, the layers used in the
+# build, and optionally, additional lines to be appended to the generated conf/bblayers.conf . It has this format:
+#
+# McfFileVersion = 2  (If this setting is absent, version 1 is assumed.)
+#
+# Distribution = 'DISTRO'
+#
+# Machines = ['MACHINE1', 'MACHINE2', ...]
+#
+# Layers = [
+# (layer-name: str, priority: int, URL: str, fetch: dict, options: dict),
+# ...
+# ]
+#
+#   where:
+#
+#   layer-name  = Unique identifier; it represents the layer, whose location must contain a conf/layer.conf.
+#
+#   priority    = Integer layer priority as defined by OpenEmbedded. It also  specifies the order in which layers are searched for
+#                 files. Larger values have higher priority. In also determines the order of layer updates. A value of -1
+#                 indicates that the entry is not for a metadata layer; for example, bitbake.
+#
+#   URL         = Git repository address of the layer from which to clone. A value of '' skips the cloning.
+#
+#   fetch       = Information used by Git to fetch the layer and to name the local branch. This item is a dict with the form:
+#                       { ['branch': '<remote-branch-name>'] [,] ['commit': '<id|tag>'] }
+#                 The default for <remote-branch-name> is the branch pointed to by "origin/HEAD", which is usually "master". If
+#                 "commit" is not present, the current head of <remote-branch-name> is fetched. Note that the commit fetched is
+#                 not required lie along <remote-branch-name>. If the value of the item is {}, no fetch is done for the layer.
+#
+#                 The file version 1 str form of the item continues to be recognized:
+#                      '[branch=<remote-branch-name>][,][commit=<id|tag>]'
+#
+#   options    = Layer options. This item is a dict with this key recognized:
+#                       'location': '<alternative-directory>'       Passed as the <directory> argument to "git clone".
+#
+#                The file version 1 str form of the item continues to be recognized as the value for <alternative-directory>.
+#
+# BblayersConfExtraLines = ['LINE1',    (This setting is optional.)
+#                           'LINE2',
+#                           ...
+#                           ]
+
+
 import argparse
 import errno
 import logging
@@ -26,7 +71,7 @@ import glob
 import importlib.util
 import importlib.machinery
 
-__version__ = "7.1.0"
+__version__ = "7.1.1"
 
 logger = logging.getLogger(__name__)