[Fuego] [PATCH] Docs: Convert tbwiki pages into .rst files

* [Fuego] [PATCH] Docs: Convert tbwiki pages into .rst files
@ 2020-11-25  6:14 Pooja
  2020-12-02 21:45 ` Bird, Tim
  0 siblings, 1 reply; 8+ messages in thread
From: Pooja @ 2020-11-25  6:14 UTC (permalink / raw)
  To: tbird20d, Tim.Bird; +Cc: fuego, Pooja More

From: Pooja More <pooja.sm@pathpartnertech.com>

Following pages are converted:
Coding_style.rst
Fuego_directories.rst
Glossary.rst

Signed-off-by: Pooja More <pooja.sm@pathpartnertech.com>
---
 docs/rst_src/Coding_style.rst      | 111 +++++++++++++++
 docs/rst_src/Fuego_directories.rst | 161 +++++++++++++++++++++
 docs/rst_src/Glossary.rst          | 277 +++++++++++++++++++++++++++++++++++++
 3 files changed, 549 insertions(+)
 create mode 100644 docs/rst_src/Coding_style.rst
 create mode 100644 docs/rst_src/Fuego_directories.rst
 create mode 100644 docs/rst_src/Glossary.rst

diff --git a/docs/rst_src/Coding_style.rst b/docs/rst_src/Coding_style.rst
new file mode 100644
index 0000000..a190b13
--- /dev/null
+++ b/docs/rst_src/Coding_style.rst
@@ -0,0 +1,111 @@
+###############
+Coding Style
+###############
+
+This page described the coding style conventions used in Fuego.
+
+Please adhere to these conventions, so that the code has a more
+uniform style and it is easier to maintain.  Not all code in Fuego
+adheres to these styles. As we work on code, we will convert it to the
+preferred style over time. New code should adhere to the preferred
+style.
+
+Fuego code consists mostly of shell script and python code.
+
+===============================
+Indentation and line length
+===============================
+
+We prefer indentation to be 4 spaces, with no tabs.
+
+It is preferred to keep lines within 80 columns.  However, this is not
+strict.  If a string constant causes a line to run over 80 columns,
+that is OK.
+
+Some command sequences passed to the 'report' function may be quite
+long and require that they be expressed on a single line.  In that
+case, you can break them up onto multiple lines using shell
+continuation lines.
+
+=======================
+Trailing whitespace
+=======================
+
+Lines should not end in trailing whitespace.  That is: 'grep " $" *'
+should always be empty.
+
+You can do this with: 'grep -R " $" *' in the directory you're working
+in, and fix the lines manually.
+
+Or, another method, if you're using vim, is to add an autocmd to your
+.vimrc to automatically remove whitespace from lines that you edit.
+
+This line in your ~/.vimrc:
+
+::
+
+  autocmd FileType sh,c,python autocmd BufWritePre <buffer> %s/\s\+$//e
+
+
+automatically removes whitespace from all line endings in shell, C,
+and python files that are saved from vim.
+
+Or, a third method of dealing with this automatically is to have git
+check for whitespace errors using a configuration option, or a hook.
+See
+
+`<https://stackoverflow.com/questions/591923/make-git-automatically-remove-trailing-whitespace-before-committing#592014>`_
+
+
+Also, script files should not end in blank lines.
+
+=================
+Shell features
+=================
+
+Shell scripts which run on the device-under-test (DUT or board),
+SHOULD restrict themselves to POSIX shell features only.  Do not
+assume you have any shell features on the target board outside of
+those supported by 'busybox ash'.
+
+Try running 'checkbashisms' on your target-side code, to check for any
+non-POSIX constructs in the code.
+
+The code in ``fuego_test.sh`` is guaranteed to run in bash, and may
+contain bashisms, if needed.  If equivalent functionality is available
+using POSIX features, please use those instead. Please avoid esoteric
+or little-known bash features. (Or, if you use such features, please
+comment them.)
+
+Another useful tool for checking your shell code is 'ShellCheck'.  See
+`<https://github.com/koalaman/shellcheck>`_.  Note that most
+distributions have a package for shellcheck.
+
+There are a few conventions for avoiding using too many external
+commands in shell scripts that execute on the DUT. To check for a
+process, use 'ps' and 'grep', but to avoid having grep find itself,
+use a wildcard in the search pattern.  Like so: 'ps | grep [f]oo'
+(rather than 'ps | grep foo | grep -v grep').
+
+
+================
+Python style
+================
+
+Python code (such as parser code, the overlay generator, ftc and other
+helper scripts), should be compliant with
+`<https://www.python.org/dev/peps/pep-0008/>`_.  As with shell code,
+there is a lot of legacy code in Fuego
+that is not currently compliant with PEP 8.  We will convert legacy
+code to the correct style as changes are made over time.
+
+Here are a few more conventions for Fuego code:
+
+ - Strings consisting of a single character should be declared use single-quotes
+ - Strings consisting of multiple characters should declared using double-quotes,
+   unless the string contains a double-quote.  In that case, single-quotes should
+   be using for quoting, to avoid having to escape the double-quote.
+
+Note that there is a fuego lint test (selftest), called
+Functional.fuego_lint.  It only checks a few files at the moment, but
+the plan is to expand it to check additional code in the future.
diff --git a/docs/rst_src/Fuego_directories.rst b/docs/rst_src/Fuego_directories.rst
new file mode 100644
index 0000000..5fcfe03
--- /dev/null
+++ b/docs/rst_src/Fuego_directories.rst
@@ -0,0 +1,161 @@
+#######################
+Fuego directories
+#######################
+
+This page describes the fuego directory structure,
+and what the items in each area are used for.
+
+
+========================
+Inside the container
+========================
+
+ * ``/fuego-core`` - the fuego core directory, containing tests,
+   scripts and the overlay generator for executing Fuego tests
+
+
+   * ``fuego`` - directory for fuego back-end system
+
+     * This is populated from the ``fuego-core`` repository when the container
+       is created, and provides landing places for other symlinks in the system
+     * ``engine`` - symlink for backwards compatibility with older versions
+       of Fuego tests
+     * ``overlays``
+
+       * ``base`` - contains the base fuego functions and variables
+       * ``distribs`` - contains files for defining different targert
+         distribution attributes
+       * ``testplans`` - contains testplan files (in json format)
+       * ``test_specs`` - contains test spec files (in json format)
+
+         * Note that each spec is in a named file (eg. ``Functional.bc.spec``)
+           in this directory
+
+     * ``scripts`` - core scripts which implement the Fuego test framework
+     * ``tests`` - actual test materials themselves, including the
+       base script for each test
+
+       * ``Benchmark.foo`` - has the tarfile, patches, base script, parser.py
+         and reference.log for a particular benchmark test
+       * ``Functional.bar`` - has the tarfile, patches, base script, results
+         comparison logs (*_p.log and *_n.log) for a particular functional test
+
+ * ``/fuego-ro`` - has runtime data used by Fuego, but not writable by fuego
+
+   * Note that this is bind-mounted from inside the container to the host system
+   * ``boards`` - place for board configuration files
+   * ``conf`` - place where Fuego configuration is stored
+   * ``toolchains`` - place where toolchains may be installed
+
+ * ``/fuego-rw`` - has runtime data used by the Fuego system in the
+   container, and actually stored on the host (for persistence)
+
+   * Note that this is bind-mounted from inside the container to the host system
+
+   * ``buildzone`` - place where test programs are built
+
+     * ``Functional.foo-platform-name`` - directory for build materials
+       for that test and platform combination
+
+   * ``logs`` - place where test run logs are stored
+
+     * ``Functional.<test_name>`` - log files for a particular test test
+
+       * ``<board>.<spec>.<build_id>.<build_number>`` - the 'run' directory
+         for a test execution
+
+         * ``devlog.txt`` - the developer log for a test - list of operations
+           executed during the test
+         * ``syslogs.<time>.txt`` - system logs for test runs (from the target)
+           (before the test and after the test)
+         * ``testlog.txt`` - test logs for test runs (from the actual test programs)
+         * ``consolelog.txt`` - link to Jenkins console log, or local file,
+           if test was executed using ftc
+
+     * ``Benchmark.<test_name>`` - logs files for a benchmark test
+
+       * plot.data
+       * plot.png
+       * ``<board>.<spec>.<build_id>.<build_number>`` -
+         the 'run' directory for a test execution
+
+         * all of the above, plus:
+         * ``Benchmark.<test_name>.info.json``
+         * ``Benchmark.<test_name>.<metric>.json``
+
+   * ``boards`` - place where board-specific test data is stored
+
+
+
+ * ``/var/lib/jenkins`` - where Jenkins system configuration and data files live
+
+   * ``jobs`` - holds the Jenkins test definition files (``config.xml`` for each test) as well
+     as test output for each test run
+
+            * ``<jobname>``
+
+              * ``builds`` - data about all test runs for this test
+
+                * ``<build_number>`` - jenkins data and console log for a
+                  particular test run (``build.xml`` and log)
+
+   * ``plugins`` - place where Jenkins stores plugin code and data
+
+     * This is populated from the fuego source repository ``frontend-install/plugins``
+       when the container is created
+
+   * ``userContent`` - material that is served by Jenkins for the user interface
+
+     * ``docs`` - has the Fuego PDF documents
+     * ``fuego.logs`` - link to ``/fuego-rw/logs`` - so that logs are accessible
+       from Jenkins user interface
+
+   * ``updates`` - used for Jenkins update operations
+   * ``logs`` - has Jenkins process logs
+
+     * ``slaves`` - has Jenkins control logs for each target board
+
+       * ``<target>`` - has the slave logs for the indicated target
+
+
+=====================================
+In the 'fuego' source repository
+=====================================
+
+ * ``docs`` - contains documentation for the Fuego system
+ * ``frontend-install`` - has material for configuring the Jenkins
+   installation for Fuego
+
+    * ``plugins`` - has plugins installed to Jenkins in the docker container
+
+      * ``flot-plotter-plugin`` source for the flot plotting plugin
+
+ * ``fuego-host-scripts`` - contains scripts for creating and launching
+   the fuego container
+ * ``fuego-scripts`` - contains miscellaneous scripts used at
+   container build time and runtime
+ * ``fuego-ro`` - has runtime data used by the Fuego system in the container
+ * ``fuego-rw`` - has runtime data used by the Fuego system in the container
+
+
+========================================
+In the 'fuego-core' source repository
+========================================
+
+ * ``engine`` - symlink for backwards compatibility with tests from
+   older Fuego versions
+ * ``overlays`` - has the fuego script system and data
+
+   * ``base`` - contains the base fuego functions and variables
+   * ``distribs`` - contains files for defining different targert
+     distribution attributes
+   * ``testplans`` - contains testplan files (in json format)
+
+ * ``scripts`` - core scripts which implement the Fuego test framework
+ * ``tests`` - has the actual test materials themselves, including the
+   base script for each test
+
+   * ``Benchmark.foo`` - has the tarfile, patches, base script, ``parser.py``
+     and ``reference.log`` for a particular benchmark test
+   * ``Functional.bar`` - has the tarfile, patches, base script, results
+     comparison logs (*_p.log and *_n.log) for a particular functional test
diff --git a/docs/rst_src/Glossary.rst b/docs/rst_src/Glossary.rst
new file mode 100644
index 0000000..61bb3d7
--- /dev/null
+++ b/docs/rst_src/Glossary.rst
@@ -0,0 +1,277 @@
+##############
+Glossary
+##############
+
+Here is a glossary of terms used in this wiki:
+
+Here is a short table that relates a few Jenkins terms to Fuego terms:
+
+show_sort_link=0
+
+show_edit_links=0
+
+Table:
+
++--------------+------------------+------------------------------------------------------------------------------------------------+
+| Jenkins term |Fuego term        |Description                                                                                     |
++==============+==================+================================================================================================+
+|slave         |''none''          |this is a long-running jenkins process, that executes jobs.  It is usually (?) assigned to a    |
+|              |                  |particular node                                                                                 |
++--------------+------------------+------------------------------------------------------------------------------------------------+
+|node          |board             |item being tested (Fuego defines a Jenkins node for each board in the system)                   |
++--------------+------------------+------------------------------------------------------------------------------------------------+
+|job           |test              |a collection of information needed to perform a single test                                     |
++--------------+------------------+------------------------------------------------------------------------------------------------+
+|''none''      |request           |a request to run a particular test on a board                                                   |
++--------------+------------------+------------------------------------------------------------------------------------------------+
+|build         |run(or 'test run')|the results from executing the job or test                                                      |
++--------------+------------------+------------------------------------------------------------------------------------------------+
+|''none''      |plan              |the plan has the list of tests and how to run them (which variation, or 'spec' to use)          |
++--------------+------------------+------------------------------------------------------------------------------------------------+
+|''none''      |spec              |the spec indicates a particular variation of a test                                             |
++--------------+------------------+------------------------------------------------------------------------------------------------+
+
+=====
+B
+=====
+
+``base test script``
+
+  This is a small script associated with a particular test.  It
+  provides a set of test functions that are executed on the host (in the
+  container) when a test is run.
+
+``benchmark``
+
+  A type of test where one or more numeric metrics indicates the status
+  of the test.  See :ref:`Benchmark parser notes`
+  for more information about processing these metrics.
+
+``binary package``
+
+  A tarfile containing the materials that would normally be deployed to
+  the board for execution.
+
+``board file``
+
+  A file that describes (using environment variables) the attributes of
+  a target board.  This has the extension .board and is kept in the
+  directory ``/fuego-ro/boards``.
+
+
+====
+C
+====
+
+``console log``
+
+  The full output of execution of a test from Jenkins.
+  See :ref:`Log files` for details.
+
+=====
+D
+=====
+
+
+``devlog``
+
+  The developer log for a test.
+  See :ref:`Log files` for details.
+
+``Device``
+
+  The name of a target board in the Fuego system.
+
+``device under test``
+
+  In test terminology, this refers to the item being tested.
+  In Fuego, this may also be called the ''Device'', ''target'', or ''node''.
+
+``distribution``
+
+  This refers to a set of software that is running on a Linux machine.
+  Example "distributions" are Debian, Angstrom or Android. The
+  distribution defines file locations, libraries, utilities and several
+  important facilities and services of the machine (such as the init
+  process, and the logger).
+
+=====
+F
+=====
+
+``functional test``
+
+  A type of test that returns a single pass/fail result, indicating
+  whether the device under test.  It may include lots of sub-tests.
+
+====
+J
+====
+
+``Jenkins``
+
+  An advanced continuous integration system, used as the default
+  front-end for the Fuego test framework. see :ref:`Jenkins`
+
+``log file``
+
+  Several log files are created during execution of a test.  For details
+  about all the different log files, see :ref:`Log files`.
+
+``job``
+
+  In Jenkins terminology, a job is a test
+
+====
+M
+====
+
+``metric``
+
+  A numeric value measured by a benchmark test as the result
+  of the test.  This is compared against a threshold value to determine
+  if the test passed or failed.  See :ref:`Benchmark
+  parser notes`
+
+=====
+O
+=====
+
+``ovgen.py``
+
+  Program to collect "overlay" data from various scripts and data
+  files, and produce the final test script to run.
+  see :ref:`Overlay Generation`.
+
+=====
+P
+=====
+
+``parsed log``
+
+  The test log file after it has been filtered by log_compare.
+  See :ref:`Log files` for details.
+
+``parser.py``
+
+  A python program, included with each Benchmark test, to scan the test
+  log for benchmark metrics, check each against a reference threshold,
+  and produce a plot.png file for the test.  See :ref:`parser.py` and
+  :ref:`Benchmark parser notes` for more information.
+
+``provision``
+
+  To provision a board is to install the system software on it.  Some
+  board control systems re-provision a board for every test.  In
+  general, Fuego runs a series of tests with a single system software
+  installation.
+
+=====
+R
+=====
+
+``reference log``
+
+  This file (called "reference.log") defines the regression threshhold
+  (and operation) for each metric of a benchmark test.  See
+  :ref:`reference.log` and :ref:`Benchmark parser notes`
+
+====
+S
+====
+
+``spec variable``
+
+  A test variable that comes from a spec file. See
+  :ref:`Test variables`
+
+``stored variable``
+
+  A test variable that is stored in a read/write file, and can be
+  updated manually or programmatically.  See
+  :ref:`Test variables`
+
+``syslog``
+
+  The system log for a test.  This is the system log collected during
+  execution of a test.  See :ref:`Log files` for details.
+
+
+====
+T
+====
+
+``test``
+
+  This is a collection of scripts, jenkins configuration, source code,
+  and data files used to validate some aspect of the device under test.
+  See :ref:`Fuego Object Details` for more information.
+
+``test log``
+
+  This is the log output from the actual test program on the target.
+  There are multiple logs created during the execution of a test, and
+  some might casually also be called "test logs".  However, in this
+  documentation, the term "test log" should be used only to refer to the
+  test program output.  See :ref:`Log files` for details.
+
+``test package``
+
+  This is a packaged version of a test, including all the materials
+  needed to execute the test on another host.  See :ref:`Test
+  package system`
+
+``test phases``
+
+  Different phases of test execution defined by Fuego: pre_test, build,
+  deploy, test_run, get_testlog, test_processing, post_test.  For a
+  description of phases see: :ref:`fuego test phases`
+
+``test program``
+
+  A program that runs on the target to execute a test and output the
+  results.  This can be a compiled program or a shell script (in which
+  case the build step is empty)
+
+``test run``
+
+  This is a single instance of a test execution, containing logs and
+  other information about the run.  This is referred to in Jenkins as a
+  'build'.
+
+``test script``
+
+  The shell script that interfaces between the fuego core system and a
+  test program.  The script declares a tarfile, and functions to build,
+  deploy and run the test.  The test script runs on the host.  This is
+  also called the 'base test script'.  For details about the environment
+  that a script runs in or the functions it may call, see :ref:`Variables`,
+  :ref:`Core interfaces`, and :ref:`Test Script APIs`.
+
+``test variable``
+
+  This is the name of a variable available to the a test during it's
+  execution.  See :ref:`Test variables`.
+
+``test variable script``
+
+  the shell script that interfaces between the fuego core system and a
+  test program. The script declares a tarfile, and functions to build,
+  deploy and run the test. The test script runs on the host. This is
+  also called the 'base test script'. For details about the environment
+  that a script runs in or the functions it may call, see :ref:`Variables`,
+  :ref:`Core interfaces`, and :ref:`Test Script APIs`.
+
+
+``TOOLCHAIN``
+
+  Defines the toolchain or SDK for the device.  This is used to select a
+  set of environment variables to define and configure the toolchain for
+  building programs for the intended test target.
+
+``tools.sh``
+
+  File containing the definition of toolchain variables for the
+  different platforms installed in the container (and supported by the
+  test environment)  See :ref:`tools.sh` for details.
+
-- 
2.7.4


-- 






This
message contains confidential information and is intended only 
for the
individual(s) named. If you are not the intended
recipient, you are 
notified that disclosing, copying, distributing or taking any
action in 
reliance on the contents of this mail and attached file/s is strictly
prohibited. Please notify the
sender immediately and delete this e-mail 
from your system. E-mail transmission
cannot be guaranteed to be secured or 
error-free as information could be
intercepted, corrupted, lost, destroyed, 
arrive late or incomplete, or contain
viruses. The sender therefore does 
not accept liability for any errors or
omissions in the contents of this 
message, which arise as a result of e-mail
transmission.

^ permalink raw reply related	[flat|nested] 8+ messages in thread