[Fuego] [PATCH] docs: .rst files for pages categorized as Explanation, Tutorials and How Tos.
Pooja Sanjay More
pooja.sm at pathpartnertech.com
Fri Sep 25 11:58:51 UTC 2020
Hi,
Regarding inline commands, we can follow below convention:
:command:`any-inline-command`
Reference: <
https://docs.openstack.org/doc-contrib-guide/rst-conv/inline-markups.html#command
>
Thanks and regards,
Pooja More
On Fri, Sep 25, 2020 at 5:30 AM Bird, Tim <Tim.Bird at sony.com> wrote:
> Here is more feedback on this patch, starting with
> Building_Documentation.rst
>
> See below for inline comments.
>
> > -----Original Message-----
> > From: Pooja More <pooja.sm at pathpartnertech.com>
> >
> > convert the following pages from the fuegotest wiki
> > into rst format and add to the Fuegl rst documentation directory:
> > Adding_a_Board, Adding_a_new_test, Adding_a_toolchain,
> > Adding_or_Customizing_a_Distribution, Adding_test_jobs_to_Jenkins,
> > Adding_views_to_Jenkins,Architecture,Artwork, Building_Documentation,
> > FAQ.rst, FrontPage, Fuego_Quickstart_Guide, Fuego_naming_rules,
> > Installing_Fuego, License_And_Contribution_Policy
> > OSS_Test_Vision, Parser_module_API, Quick_Setup_Guide,
> > Raspberry_Pi_Fuego_Setup,Test_variables,
> > Using_Batch_tests, Using_the_qemuarm_target.
> >
> > Signed-off-by: Pooja More <pooja.sm at pathpartnertech.com>
> > ---
> > docs/rst_src/Adding_a_Board.rst | 242 +++++++------
> > docs/rst_src/Adding_a_new_test.rst | 230 ++++++++-----
> > docs/rst_src/Adding_a_toolchain.rst | 224 +++++++++++-
> > .../Adding_or_Customizing_a_Distribution.rst | 130 ++++---
> > docs/rst_src/Adding_test_jobs_to_Jenkins.rst | 136 +++++++-
> > docs/rst_src/Adding_views_to_Jenkins.rst | 68 ++--
> > docs/rst_src/Architecture.rst | 375
> +++++++++++----------
> > docs/rst_src/Artwork.rst | 7 +-
> > docs/rst_src/Building_Documentation.rst | 25 +-
> > docs/rst_src/FAQ.rst | 49 +++
> > docs/rst_src/FrontPage.rst | 43 ++-
> > docs/rst_src/Fuego_Quickstart_Guide.rst | 255 ++++++++++++++
> > docs/rst_src/Fuego_naming_rules.rst | 126 ++++---
> > docs/rst_src/Installing_Fuego.rst | 235 +++++++------
> > docs/rst_src/License_And_Contribution_Policy.rst | 137 ++++----
> > docs/rst_src/OSS_Test_Vision.rst | 349
> +++++++++++++++++++
> > docs/rst_src/Parser_module_API.rst | 114 ++++---
> > docs/rst_src/Quick_Setup_Guide.rst | 161 +++++++++
> > docs/rst_src/Raspberry_Pi_Fuego_Setup.rst | 73 ++--
> > docs/rst_src/Test_variables.rst | 206 ++++++-----
> > docs/rst_src/Using_Batch_tests.rst | 240 +++++++------
> > docs/rst_src/Using_the_qemuarm_target.rst | 38 ++-
> > docs/rst_src/Working_with_remote_boards.rst | 63 ++--
> > docs/rst_src/index.rst | 4 +-
> > docs/rst_src/integration_with_ttc.rst | 83 +++--
> > 25 files changed, 2575 insertions(+), 1038 deletions(-)
> > create mode 100644 docs/rst_src/FAQ.rst
> > create mode 100644 docs/rst_src/Fuego_Quickstart_Guide.rst
> > create mode 100644 docs/rst_src/OSS_Test_Vision.rst
> > create mode 100644 docs/rst_src/Quick_Setup_Guide.rst
> >
> ....
>
> > diff --git a/docs/rst_src/Building_Documentation.rst
> b/docs/rst_src/Building_Documentation.rst
> > index 4a56a22..861a44a 100644
> > --- a/docs/rst_src/Building_Documentation.rst
> > +++ b/docs/rst_src/Building_Documentation.rst
> > @@ -4,16 +4,19 @@
> > Building Documentation
> > ##########################
> >
> > -As of July, 2020, the Fuego documentation is currently available in 3
> places:
> > +As of July, 2020, the Fuego documentation is currently available in 3
> > +places:
> >
> > - * the fuego-docs.pdf generated from TEX files in the fuego/docs/source
> directory
>
> I'd like to mark filenames with accent marks, like this ``fuego-docs.pdf``
>
> This is on a 'best-effort' basis. I don't expect you to catch all of them,
> but if you happen to see directory and filenames, please accent-quote them
> so they stand out in the generated docs.
>
> > - * the Fuegotest wiki, located at: `<
> https://fuegotest.org/wiki/Documentation>`_
> > + * the fuego-docs.pdf generated from TEX files in the fuego/docs/source
>
> ``fuego/docs/rst_src``
>
> > + directory
> > + * the Fuegotest wiki, located at:
> > + `<https://fuegotest.org/wiki/Documentation>`_
> > * .rst files in fuego/docs
>
> I reworded these bullet lines. In general, as I do my review I'm adjusting
> wording, and updating information. This conversion is giving me a chance
> to review a lot of the documentation, which is really good.
>
> > -The fuego-docs.pdf file is a legacy file that is several years old. It
> > -is only kept around for backwards compatibility. It might be worthwhile
> > -to scan it and see if any information is in it that is not in the wiki
> > -and migrate it to the wiki.
> > +The fuego-docs.pdf file is a legacy file that is several years old.
> ``fuego-docs.pdf``
>
> > +It is only kept around for backwards compatibility. It might be
> > +worthwhile to scan it and see if any information is in it that is not
> > +in the wiki and migrate it to the wiki.
> >
> > The fuegotest wiki has the currently-maintained documentation for the
> > project. But there are several issues with this documentation:
> > @@ -26,9 +29,9 @@ project. But there are several issues with this
> documentation:
> >
> > - there is a mixture of information in the wiki
> >
> > - - not just documentation, but a crude issues tracker, random
> technical notes
> > - testing information, release information and other data that
> should not be
> > - part of official documentation
> > + - not just documentation, but a crude issues tracker, random
> > + technical notes testing information, release information and
> > + other data that should not be part of official documentation
> >
> > The .rst files are intended to be the future documentation source for
> > the project.
> > @@ -49,7 +52,7 @@ building the RST docs
> > ===========================
> >
> > The RST docs can be build in several different formats, including
> > -text, html, and pdf. You can type 'make help' to get a list of the
> > +text, html, and pdf. You can type 'make help' to get a list of the
>
> I'm not sure what quoting to use for commands, maybe accent-double-quote
> (which is referred to in cheat sheets as 'verbatim' style).
>
> Do you have an opinion on this? I'd like to decide on a single style,
> and be consistent throughout the docs.
>
> I'm starting to gather guidelines for the documentation conventions
> (which markup to use for what documentation elements, besides
> the items already on Markup_Mapping), and have put
> some notes at:
> http://fuegotest.org/wiki/rst_docs#Fuego_wiki_Documentation_conventions
>
>
> > possible build targets for this documentation. Output is always
> > directed to a directory under fuego/docs/_build.
> >
> > diff --git a/docs/rst_src/FAQ.rst b/docs/rst_src/FAQ.rst
> > new file mode 100644
> > index 0000000..001a008
> > --- /dev/null
> > +++ b/docs/rst_src/FAQ.rst
> > @@ -0,0 +1,49 @@
> > +.. _faq:
> > +
> > +#####
> > +FAQ
> > +#####
> > +
> > +Here is a list of Frequently Asked Questions and Answers about Fuego:
> > +
> > +===========================
> > +Languages and formats used
> > +===========================
> > +
> > +Q. Why does Fuego use shell scripting as the language for tests?
> > +==================================================================
> > +
> > +There are other computer languages which have more advanced features
> > +(such as data structions, object orientation, rich libraries,
> > +concurrency, etc.) than shell scripting. It might seem odd that shell
> > +scripting was chosen as the language for implementing the base scripts
> > +for the tests in fuego, given the availability of these other
> > +languages.
> > +
> > +The Fuego architecture is specifically geared toward host/target
> > +testing. In particular, tests often perform a variety of operations
> > +on the target in addition to the operations that are performed on the
> > +host. When the base script for a test runs on the host machine,
> > +portions of the test are invoked on the target. It is still true
> > +today that the most common execution environment (besides native code)
> > +that is available on almost every embedded Linux system is a
> > +POSIX-compliant shell. Even devices with very tight memory
> > +requirements usually have a busybox 'ash' shell available.
> > +
> > +In order to keep the base script consistent, Fuego uses shell
> > +scripting on both the host and target systems. Shell operations are
> > +performed on the target using 'cmd', 'report' and 'report_append'
> > +functions provided by Fuego.
> > +
> > +Note that Fuego officially use 'bash' as the shell on the host, but
> > +does not require a particular shell implementatio to be available on
> > +the target. Therefore, it is important to use only POSIX-compatible
> > +shell features for those aspects of the test that run on target.
> > +
> > +
> > +
> > +
> > +
> > +
> > +
> > +
> Can remove these trailing lines.
>
> > diff --git a/docs/rst_src/FrontPage.rst b/docs/rst_src/FrontPage.rst
> > index d68cafa..4f9e7a3 100644
> > --- a/docs/rst_src/FrontPage.rst
> > +++ b/docs/rst_src/FrontPage.rst
> > @@ -1,3 +1,4 @@
> > +.. _front-page:
> >
> > ##################
> > Fuego Test System
> > @@ -28,7 +29,9 @@ in 2016. The slides and a video are provided below,
> if you want
> > to see an overview and introduction to Fuego.
> >
> > The slides are here:
> > -`Introduction-to-Fuego-LCJ-2016.pdf <
> http://fuegotest.org/ffiles/Introduction-to-Fuego-LCJ-2016.pdf>`_, along
> with a
> > +`Introduction-to-Fuego-LCJ-2016.pdf
> > +<http://fuegotest.org/ffiles/Introduction-to-Fuego-LCJ-2016.pdf>`_,
> > +along with a
> > `YouTube video <https://youtu.be/AueBSRN4wLk>`_.
> > You can find more presentations about Fuego on our wiki at:
> > `<http://fuegotest.org/wiki/Presentations>`_.
> > @@ -39,12 +42,13 @@ Getting Started
> > ================
> >
> > There are a few different ways to get started with Fuego:
> > - 1. Use the `Fuego Quickstart Guide <quickstart_guide>`_ to
> > + 1. Use the :ref:`Fuego Quickstart Guide <quickstart_guide>` to
> > get Fuego up an running quickly.
> > - 2. Or go through our `Install and First Test <install_and_first_test>`_
> > + 2. Or go through our :ref:`Install and First Test
> > + <install_and_first_test>`
> > tutorial to install Fuego and run a test on a single "fake" board.
> > - This will give you an idea of basic Fuego operations, without
> having to
> > - configure Fuego for your own board
> > + This will give you an idea of basic Fuego operations, without
> > + having to configure Fuego for your own board
> > 3. Work through the documentation for :ref:`Installation
> <installfuego>`
> >
> > Where to download
> > @@ -57,20 +61,20 @@ Code for the test framework is available in 2 git
> repositories:
> > The fuego-core directory resides inside the fuego directory.
> > But normally you do not clone that repository directly. It is cloned
> > for you during the Fuego install process. See the
> > -`Fuego Quickstart Guide <quickstart_guide>`_ or the
> > +:ref:`Fuego Quickstart Guide <quickstart_guide>` or the
> > :ref:`Installing Fuego <installfuego>` page for more information.
> >
> > ===============
> > Documentation
> > ===============
> > -For more complete documentation, see the following areas:
> > +See the index below for links to the major sections of the documentation
> > +for Fuego. The major sections are:
> >
> > - * Installation_ has information about installation and
> > - administration documentation for Fuego.
> > - * `User Guides <user-guides>`_ has User documentation for Fuego.
> > - * `Developer Info <developer_info>`_ has information for test
> developers and
> > - people who want to extend Fuego
> > - * `Reference Material <reference_material>`_ has APIs and other
> material about Fuego
> > + * :ref:`Tutorials <tutor>`
> > + * :ref:`Installation and Administration <admin>`
> > + * :ref:`User Guides <user_guides>`
> > + * :ref:`Developer Resources <dev_res>`
> > + * :ref:`API Reference <api_rex>`
> >
> > ============
> > Resources
> > @@ -112,7 +116,9 @@ It can be summed up like this:
> > ..
> > FIXTHIS - 'admonition:: Vision' didn't work with rtd theme
> >
> > -.. Note:: Do for testing what open source has done for coding
> > +.. note::
> > + Do for testing
> > + what open source has done for coding
> >
> > There are numerous aspects of testing that are still done in an ad-hoc
> > and company-specific way. Although there are open source test
> > @@ -164,7 +170,7 @@ deploy and run them, and tools to analyze, track,
> and visualize test
> > results.
> >
> > For more details about a high-level vision of open source testing,
> > -please see `OSS Test Vision <oss>`_.
> > +please see :ref:`OSS Test Vision <oss>`.
> >
> > ================
> > Other Resources
> > @@ -174,13 +180,14 @@ Historical information
> > ----------------------
> >
> >
> > -`<http://elinux.org/Fuego>`_ has some historical information about
> Fuego.
> > +`<http://elinux.org/Fuego>`_ has some historical information about
> > +Fuego.
> >
> > Related systems
> > ---------------
> >
> > -See :ref:`Other test systems <ots>` for notes about other test
> frameworks
> > -and comparisons between Fuego and those other systems.
> > +See :ref:`Other test systems <ots>` for notes about other test
> > +frameworks and comparisons between Fuego and those other systems.
> >
> > Things to do
> > ------------
> > diff --git a/docs/rst_src/Fuego_Quickstart_Guide.rst
> b/docs/rst_src/Fuego_Quickstart_Guide.rst
>
> This (Fuego_Quickstart_Guide.rst) has been moved to just
> "Quickstart_Guide.rst"
>
> In general, I'd like to remove "Fuego_" from the filenames in most cases.
>
> ...
>
> > diff --git a/docs/rst_src/Fuego_naming_rules.rst
> b/docs/rst_src/Fuego_naming_rules.rst
>
> I probably want to rename this to just Naming_Rules.rst
>
> > index 3cb172a..8cd4446 100644
> > --- a/docs/rst_src/Fuego_naming_rules.rst
> > +++ b/docs/rst_src/Fuego_naming_rules.rst
> > @@ -18,7 +18,8 @@ Fuego test name
> > * 'Functional.'
> > * 'Benchmark.'
> >
> > - * the name following the prefix is known as the base test name, and
> has the following rules:
> > + * the name following the prefix is known as the base test name, and
> > + has the following rules:
> >
> > * it may only use letters, numbers and underscores
> >
> > @@ -26,7 +27,8 @@ Fuego test name
> >
> > * it may use upper and lower case letters
> >
> > - * All test definition materials reside in a directory with the full
> test name:
> > + * All test definition materials reside in a directory with the full
> > + test name:
> >
> > * e.g. Functional.hello_world
> >
> > @@ -75,7 +77,8 @@ The following sections describe the names used for
> these elements.
> > Node name
> > ===================
> >
> > - * A Jenkins node corresponding to a board must have the same name as
> the board.
> > + * A Jenkins node corresponding to a board must have the same name as
> > + the board.
> >
> > * e.g. beaglebone
> >
> > @@ -83,7 +86,8 @@ Job name
> > =============
> >
> > * A Jenkins job is used to execute a test.
> > - * Jenkins job names should consist of these parts:
> <board>.<spec>.<test_name>
> > + * Jenkins job names should consist of these parts:
> > + <board>.<spec>.<test_name>
> >
> > * e.g. beaglebone.default.Functional.hello_world
> >
> > @@ -93,14 +97,17 @@ Job name
> > Run identifier
> > ===================
> >
> > -A Fuego run identifier is used to refer to a "run" of a test - that is
> a particular invocation of a test and it's resulting output, logs and
> > artifacts.
> > -A run identifier should be unique throughout the world, as these are
> used
> > -in servers where data from runs from different hosts are stored.
> > +A Fuego run identifier is used to refer to a "run" of a test - that is
> > +a particular invocation of a test and it's resulting output, logs and
> > +artifacts. A run identifier should be unique throughout the world, as
> > +these are used in servers where data from runs from different hosts
> > +are stored.
> >
> > -The parts of a run id are separated by dashes, except that the separator
> > -between the host and the board is a colon.
> > +The parts of a run id are separated by dashes, except that the
> > +separator between the host and the board is a colon.
> >
> > -A fully qualified (global) run identifier consist of the following
> parts:
> > +A fully qualified (global) run identifier consist of the following
> > +parts:
> >
> > * test name
> > * spec name
> > @@ -109,16 +116,17 @@ A fully qualified (global) run identifier consist
> of the following parts:
> > * host
> > * board
> >
> > -FIXTHIS - global run ids should include timestamps to make them
> globally unique for all time
> > +FIXTHIS - global run ids should include timestamps to make them
> > +globally unique for all time
> >
> >
> > Example:
> > Functional.LTP-quickhit-3-on-timdesk:beaglebone
> >
> >
> > -A shortened run identifier may omit the *on* and *host*. This is
> referred to
> > -as a local run id, and is only valid on the host where the run was
> > -produced.
> > +A shortened run identifier may omit the *on* and *host*. This is
> > +referred to as a local run id, and is only valid on the host where the
> > +run was produced.
> >
> > Example:
> > * Functional.netperf-default-2-minnow
> > @@ -131,17 +139,20 @@ timestamp
> >
> > * e.g. 2017-03-29_10:25:14
> >
> > - * times are expressed in localtime (relative to the host where they
> are created)
> > + * times are expressed in localtime (relative to the host where they
> > + are created)
> >
> > ====================
> > test identifiers
> > ====================
> >
> > Also know as TGUIDs (or test globally unique identifiers), a test
> > -identifier refers to a single unit of test operation or result from the
> test system.
> > -A test identifier may refer to a testcase or an individual test measure.
> > +identifier refers to a single unit of test operation or result from
> > +the test system. A test identifier may refer to a testcase or an
> > +individual test measure.
> >
> > -They consist of a several parts, some of which may be omitted in some
> circumstances
> > +They consist of a several parts, some of which may be omitted in some
> > +circumstances
> >
> > The parts are:
> >
> > @@ -154,14 +165,15 @@ Legal characters for these parts are letters,
> numbers, and underscores.
> > Only testset names may include a period ("."), as that is used as the
> > separator between constituent parts of the identifier.
> >
> > -testcase identifiers should be consistent from run-to-run of a test, and
> > -should be globally unique.
> > +testcase identifiers should be consistent from run-to-run of a test,
> > +and should be globally unique.
> >
> > test identifiers may be in fully-qualified form, or in shortened
> > form - missing some parts. The following rules are used to convert
> > between from shortened forms to fully-qualified forms.
> >
> > -If the testsuite name is missing, then the base name of the test is
> used.
> > +If the testsuite name is missing, then the base name of the test is
> > +used.
> >
> > * e.g. Functional.jpeg has a default testsuite name of "jpeg"
> >
> > @@ -172,23 +184,34 @@ A test id may refer to one of two different items:
> > * a testcase id
> > * a measure id
> >
> > -A fully qualified test identifier consists of a testsuite name, testset
> name and a testcase name. Shortened names may be used, in which
> > case default values will be used for some parts, as follows:
> > +A fully qualified test identifier consists of a testsuite name,
> > +testset name and a testcase name. Shortened names may be used, in
> > +which case default values will be used for some parts, as follows:
> >
> > -If a result id has only 1 part, it is the testcase name. The testset
> name is considered to be *default*, and the testsuite name is the base
> > name of the test.
> > +If a result id has only 1 part, it is the testcase name. The testset
> > +name is considered to be *default*, and the testsuite name is the base
> > +name of the test.
> >
> > -That is, for the fuego test Functional.jpeg, a shortened tguid of
> *test4*, the fully qualified
> > -name would be:
> > +That is, for the fuego test Functional.jpeg, a shortened tguid of
> > +*test4*, the fully qualified name would be:
> >
> > * jpeg.default.test4
> >
> > -If a result id has 2 parts, then the first part is the testset name and
> the second is the testcase name, and the testsuite name is the base
> > name of the test.
> > +If a result id has 2 parts, then the first part is the testset name
> > +and the second is the testcase name, and the testsuite name is the
> > +base name of the test.
> >
> > measure id
> > ===============
> >
> > -A measure identifier consists of a testsuide id, testset id, testcase
> id and measure name.
> > +A measure identifier consists of a testsuide id, testset id, testcase
> > +id and measure name.
> >
> > -A shortened measure id may not consist of less than 2 parts. If it
> only has 2 parts, the first part is the testcase id, and the second part is
> > the measure name. In all cases the last part of the name is the measure
> name, the second-to-last part of the name is the testcase name.
> > +A shortened measure id may not consist of less than 2 parts. If it
> > +only has 2 parts, the first part is the testcase id, and the second
> > +part is the measure name. In all cases the last part of the name is
> > +the measure name, the second-to-last part of the name is the testcase
> > +name.
> >
> > If there are three parts, the first part is the testset name.
> >
> > @@ -209,22 +232,43 @@ Dependency check variables
> > The following is the preferred format for variables used in dependency
> > checking code:
> >
> > - * **PROGRAM_FOO** - require program 'foo' on target. The program name
> is upper-cased, punctuation or spaces are replaced with '_',
> > and the name is prefixed with 'PROGRAM\_'. The value of variable is
> full path on target where program resides.
> > + * **PROGRAM_FOO** - require program 'foo' on target. The program
> > + name is upper-cased, punctuation or spaces are replaced with '_',
> > + and the name is prefixed with 'PROGRAM\_'. The value of variable
> > + is full path on target where program resides.
> >
> > * ex: PROGRAM_BC=/usr/bin/bc
> >
> > - * **HEADER_FOO** - require header file 'foo' in SDK. The header
> filename is stripped of its suffix (I don’t know if that's a good idea or
> > not), upper-cased, punctuation or spaces are replaced with '_', and the
> name is prefixed with 'HEADER\_'. The value of variable is the full
> > path in the SDK of the header file:
> > -
> > - * ex:
> HEADER_FOO=/opt/poky2.1.2/sysroots/x86_64-pokysdk-linux/usr/include/foo.h
> > -
> > -
> > - * **SDK_LIB_FOO** - require 'foo' library in SDK. The library
> filename is stripped of the 'lib' prefix and .so suffix, upper-cased,
> > punctuation and spaces are replaced with '_', and the name is prefixed
> with 'SDK_LIB\_'. The value of the variable is the full path in the
> > SDK of the library.
> > -
> > - * ex:
> SDK_LIB_FOO=/opt/poky2.1.2/sysroots/x86_64-pokysdk-linux/usr/lib/libfoo.so
> > - * Note that in case a static library is required (.a), then the
> variable name should include that suffix:
> > - * ex:
> SDK_LIB_FOO_A=/opt/poky1.2.1/sysroots/x86_64-pokysdk-linux/usr/lib/libfoo.a
> > -
> > - * **TARGET_LIB_FOO** - require 'foo' library on target. The library
> filename is stripped of the 'lib' prefix and .so suffix (not sure this is a
> > good idea, as we potentially lose a library version requirement),
> upper-cased, punctuation and spaces are replaced with '_', and the name
> > is prefixed with 'TARGET_LIB\_'. The value of the variable is the full
> path of the library on the target board.
> > + * **HEADER_FOO** - require header file 'foo' in SDK. The header
> > + filename is stripped of its suffix (I don’t know if that's a good
> > + idea or not), upper-cased, punctuation or spaces are replaced with
> > + '_', and the name is prefixed with 'HEADER\_'. The value of
> > + variable is the full path in the SDK of the header file:
> > +
> > + * ex:
> > + HEADER_FOO=/opt/poky2.1.2/sysroots/x86_64-pokysdk-
> > + linux/usr/include/foo.h
> > +
> > +
> > + * **SDK_LIB_FOO** - require 'foo' library in SDK. The library
> > + filename is stripped of the 'lib' prefix and .so suffix,
> > + upper-cased, punctuation and spaces are replaced with '_', and the
> > + name is prefixed with 'SDK_LIB\_'. The value of the variable is
> > + the full path in the SDK of the library.
> > +
> > + * ex: SDK_LIB_FOO=/opt/poky2.1.2/sysroots/x86_64-pokysdk-
> > + linux/usr/lib/libfoo.so
> > + * Note that in case a static library is required (.a), then the
> > + variable name should include that suffix:
> > + * ex: SDK_LIB_FOO_A=/opt/poky1.2.1/sysroots/x86_64-pokysdk-
> > + linux/usr/lib/libfoo.a
> > +
> > + * **TARGET_LIB_FOO** - require 'foo' library on target. The library
> > + filename is stripped of the 'lib' prefix and .so suffix (not sure
> > + this is a good idea, as we potentially lose a library version
> > + requirement), upper-cased, punctuation and spaces are replaced with
> > + '_', and the name is prefixed with 'TARGET_LIB\_'. The value of the
> > + variable is the full path of the library on the target board.
> >
> > * ex: TARGET_LIB_FOO=/usr/lib/libfoo.so
> >
> > diff --git a/docs/rst_src/Installing_Fuego.rst
> b/docs/rst_src/Installing_Fuego.rst
>
> It looks like you undid a bunch of edits and enhancement I made to this
> file. I'm undoing all these changes (I already committed this patch, but
> will back out the portions to this file.)
>
> > index 379f9ad..87fb140 100644
> > --- a/docs/rst_src/Installing_Fuego.rst
> > +++ b/docs/rst_src/Installing_Fuego.rst
> > @@ -8,8 +8,8 @@ This page describes the steps to install Fuego on your
> Linux machine.
> > It includes detailed descriptions of the operations, for both users
> > and developers.
> >
> > -.. Tip:: If you are interested in a quick outline of steps, please see
> the
> > - :ref:`Fuego Quickstart Guide <quickstart_guide>` instead.
> > +If you are interested in a quick outline of steps, please see the
> > +:ref:`Fuego Quickstart Guide <quickstart>` instead.
>
> This should have been left as a tip.
>
> >
> > ===========
> > Overview
> > @@ -17,18 +17,18 @@ Overview
> >
> > The overview of the steps is:
> >
> > - 1. install pre-requisite software
> > - 2. download the Fuego repository
> > - 3. build your Fuego container
> > - 4. start the container
> > - 5. access the Jenkins interface
> > + * 1. install pre-requisite software
> > + * 2. download the Fuego repository
> > + * 3. build your Fuego container
> > + * 4. start the container
> > + * 5. access the Jenkins interface
> This should have been left with bullets removed.
>
> >
> > =================================
> > Install pre-requisite software
> > =================================
> >
> > -To retrieve the Fuego software and create the docker image for it, you
> need
> > -to have git and docker installed on your system.
> > +To retrieve the Fuego software and create the docker image for it, you
> > +need to have git and docker installed on your system.
> >
> > On Ubuntu, try the following commands: ::
> >
> > @@ -94,11 +94,12 @@ of tests, and the main Fuego command line tool 'ftc'.
> > Downloading the repository
> > ============================
> >
> > -You can use 'git clone' to download the main 'fuego' repository, like
> so: ::
> > +You can use 'git clone' to download the main 'fuego' repository, like
> > +so: ::
> >
> >
> > - $ git clone https://bitbucket.org/fuegotest/fuego.git
> > - $ cd fuego
> > + $ git clone https://bitbucket.org/fuegotest/fuego.git
> > + $ cd fuego
>
> I changed this indent from tabs to two spaces, for this and other
> literal blocks. That's the convention I'd like to follow:
> indent literal blocks with 2 spaces
>
> I'd like to avoid tabs in the documents if possible.
>
> >
> >
> > After downloading the repositories, switch to the 'fuego' directory,
> > @@ -110,16 +111,16 @@ repository, which is the current main released
> version of Fuego.
> > Downloading a different branch
> > --------------------------------
> >
> > -If you are experimenting with an unreleased version of Fuego
> > -in the 'next' branch, then please replace the 'git clone' command in the
> > -instructions above with these: ::
> > +*NOTE:* If you are experimenting with an unreleased version of Fuego
> > +in the 'next' branch, then please replace the 'git clone' command in
> > +the instructions above with these: ::
> >
> > - $ git clone -b next https://bitbucket.org/fuegotest/fuego.git
> > - $ cd fuego
> > + $ git clone -b next https://bitbucket.org/fuegotest/fuego.git
> > + $ cd fuego
>
> Same here.
>
> >
> >
> > -This uses '-b next' to indicate a different branch to check out during
> the
> > -clone operation.
> > +This uses '-b next' to indicate a different branch to check out during
> > +the clone operation.
> >
> > ============================
> > Create the Fuego container
> > @@ -129,39 +130,41 @@ The third step of the installation is to run
> install.sh to create the
> > Fuego docker container. While in the 'fuego' directory,
> > run the script from the current directory, like so: ::
> >
> > - $ ./install.sh
> > +
> > + $ ./install.sh
> >
> >
> > install.sh uses docker and the Dockerfile in the fuego directory to
> > create a docker container with the Fuego Linux distribution.
> >
> > This operation may take a long time. It takes about 45 minutes on my
> > -machine. This is due to building a nearly complete distribution of
> Linux,
> > -from binary packages obtained from the Internet.
> > +machine. This is due to building a nearly complete distribution of
> > +Linux, from binary packages obtained from the Internet.
> >
> > This step requires Internet access. You need to make sure that
> > you have proxy access to the Internet if you are behind a corporate
> > firewall.
> >
> > -Please see the section
> > -:ref:`Alternative Installation Configurations <alt_install>` below
> > -for other arguments to ``install.sh``, or for alternative installation
> scripts.
> > +Please see the section "Alternative Installation Configuratons" below
> > +for other arguments to *install.sh*, or for alternative installation
> > +scripts.
> >
> >
> > Fuego Linux distribution
> > ===========================
> >
> > -The Fuego Linux distribution is a distribution of Linux based on Debian
> Linux,
> > -with many additional packages and tools installed. These
> > -additional packages and tools are required for aspects of Fuego
> operation,
> > -and to support host-side processes and services needed by the tests
> > -included with Fuego.
> > +The Fuego Linux distribution is a distribution of Linux based on
> > +Debian Linux, with many additional packages and tools installed.
> > +These additional packages and tools are required for aspects of Fuego
> > +operation, and to support host-side processes and services needed by
> > +the tests included with Fuego.
> >
> > For example, the Fuego distribution includes
> > * the 'Jenkins' continuous integration server
> > * the 'netperf' server, for testing network performance.
> > * the 'ttc' command, which is a tool for board farm management
> > - * the python 'jenkins' module, for interacting with Fuego's Jenkins
> instance
> > + * the python 'jenkins' module, for interacting with Fuego's Jenkins
> > + instance
> > * and many other tools, programs and modules used by Fuego and its
> tests
> >
> > Fuego commands execute inside the Fuego docker container, and Fuego
> > @@ -186,22 +189,22 @@ the '--priv' options with install.sh: ::
> > Customizing the privileged container
> > -------------------------------------
> >
> > -Note that using '--priv' causes install.sh to use a different container
> > -creation script.
> > -Normally (in the non --priv case), install.sh uses
> ``fuego-host-scripts/docker-create-container.sh``.
> > +Note that using '--priv' causes install.sh to use a different
> > +container creation script. Normally (in the non --priv case),
> > +install.sh uses ``fuego-host-scripts/docker-create-container.sh``.
> >
> > -When --priv is used, Fuego uses
> ``fuego-host-scripts/docker-create-usb-privileged-container.sh``.
> > +When --priv is used, Fuego uses
> > +``fuego-host-scripts/docker-create-usb-privileged-container.sh``.
> >
> >
> > ``docker-create-usb-privileged-container.sh`` can be edited, before
> > running install.sh, to change the set of hardware devices
> > that the docker container will have privileged access to.
> >
> > -This is done
> > -by adding more bind mount options to the 'docker create' command inside
> > -this script. Explaining exactly how to do this is outside the scope
> > -of this documentation. Please see documentation and online resources
> for
> > -the 'docker' system for information about this.
> > +This is done by adding more bind mount options to the 'docker create'
> > +command inside this script. Explaining exactly how to do this is
> > +outside the scope of this documentation. Please see documentation and
> > +online resources for the 'docker' system for information about this.
> >
> > The script currently creates bind mounts for:
> > * /dev/bus/usb - USB ports, and newly created ports
> > @@ -210,24 +213,24 @@ The script currently creates bind mounts for:
> > * /dev/serial - general serial ports, and newly created ports
> >
> > If you experience problems with Fuego accessing hardware on your host
> > -system, you may need to build the Fuego docker container using
> additional
> > -bind mounts that are specific to your configuration. Do so by
> > -editing docker-create-used-privileged-container.sh, removing the old
> container,
> > -and re-running './install.sh --priv' to build a new container with the
> > -desired privileges.
> > +system, you may need to build the Fuego docker container using
> > +additional bind mounts that are specific to your configuration. Do so
> > +by editing docker-create-used-privileged-container.sh, removing the
> > +old container, and re-running './install.sh --priv' to build a new
> > +container with the desired privileges.
> >
> > Using an different container name
> > ======================================
> >
> > By default, install.sh creates a docker image called 'fuego' and a
> > docker container called 'fuego-container'. There are some situations
> > -where it is desirable to use different names. For example, having
> different
> > -container names is useful for Fuego self-testing. It can also used
> > -to do A/B testing when
> > -migrating from one release of Fuego to the next.
> > +where it is desirable to use different names. For example, having
> > +different container names is useful for Fuego self-testing. It can
> > +also used to do A/B testing when migrating from one release of Fuego
> > +to the next.
> >
> > -You can provide a different name for the Fuego image and container,
> > -by supplying one on the command line for install.sh, like so: ::
> > +You can provide a different name for the Fuego image and container, by
> > +supplying one on the command line for install.sh, like so:
> >
> > $ ./install.sh my-fuego
> >
> > @@ -240,7 +243,8 @@ container named 'my-fuego-container'
> > Start the Fuego container
> > ===========================
> >
> > -To start the Fuego docker container, use the 'start.sh' script. ::
> > +To start the Fuego docker container, use the 'start.sh' script.
> > +
> >
> > $ ./start.sh
> >
> > @@ -266,16 +270,18 @@ ran 'start.sh' from) running for the duration of
> your testing.
> > Access the Fuego Jenkins web interface
> > =========================================
> >
> > -Fuego includes a version of Jenkins and a set of plugins as part of its
> > -system. Jenkins is running inside the Fuego docker container.
> > -By default the Fuego Jenkins interface runs on port 8090, with an URL
> path "/fuego".
> > +Fuego includes a version of Jenkins and a set of plugins as part of
> > +its system. Jenkins is running inside the Fuego docker container. By
> > +default the Fuego Jenkins interface runs on port 8090, with an URL
> > +path "/fuego".
> >
> > -Here is an example showing use of firefox to access the Jenkins
> interface
> > -with Fuego ::
> > +Here is an example showing use of firefox to access the Jenkins
> > +interface with Fuego ::
> >
> > $ firefox http://localhost:8090/fuego
> >
> > -To access the Fuego interface you can use any browser - not just
> Firefox.
> > +To access the Fuego interface you can use any browser - not just
> > +Firefox.
> >
> > In your browser, you should see a screen similar to the following:
> >
> > @@ -283,16 +289,19 @@ In your browser, you should see a screen similar
> to the following:
> > :width: 900
> >
> > Note that this web interface is available from any machine that has
> > -access to your host machine via the network. This means that test
> operations and test results are available to anyone with access to your
> > machine.
> > -You can configure Jenkins with different security to avoid this.
> > +access to your host machine via the network. This means that test
> > +operations and test results are available to anyone with access to
> > +your machine. You can configure Jenkins with different security to
> > +avoid this.
> >
> > ======================================
> > Access the Fuego docker command line
> > ======================================
> >
> > -For some Fuego operations, it is handy to use the command line (shell
> prompt)
> > -inside the docker container. In particular, parts of the remaining
> > -setup of your Fuego system involve running the 'ftc' command line tool.
> > +For some Fuego operations, it is handy to use the command line (shell
> > +prompt) inside the docker container. In particular, parts of the
> > +remaining setup of your Fuego system involve running the 'ftc' command
> > +line tool.
> >
> > Some 'ftc' commands can be run outside the container, but other require
> > that you execute the command inside the container.
> > @@ -315,8 +324,8 @@ Fuego docker container, like so: ::
> > Remaining steps
> > ===================
> >
> > -Fuego is now installed and ready for test operations. However, some
> steps
> > -remain in order to use it with your hardware. You need to:
> > +Fuego is now installed and ready for test operations. However, some
> > +steps remain in order to use it with your hardware. You need to:
> >
> > * add one or more hardware boards (board definition files)
> > * add a toolchain
> > @@ -325,18 +334,18 @@ remain in order to use it with your hardware. You
> need to:
> > These steps are described in subsequent sections of this documentation.
> >
> > See:
> > - * :ref:`Adding a Board <adding_board>`
> > + * :ref:`Adding a board <adding_board>`
> > * :ref:`Adding a toolchain <addtoolchain>`
> > * :ref:`Adding test jobs to Jenkins <addtestjob>`
> >
> > -.. _alt_install:
> > -
> > ================================================
> > Alternative installation configurations
> > ================================================
> >
> > -The default installation of Fuego installs the entire Fuego system,
> including Jenkins and the Fuego core, into a docker container running
> > on a host system, which Jenkins running on port 8090. However, it is
> possible
> > -to install Fuego in other configurations.
> > +The default installation of Fuego installs the entire Fuego system,
> > +including Jenkins and the Fuego core, into a docker container running
> > +on a host system, which Jenkins running on port 8090. However, it is
> > +possible to install Fuego in other configurations.
> >
> > The configuration alternatives that are supported are:
> > * install using a different TCP/IP port for Jenkins
> > @@ -346,50 +355,76 @@ The configuration alternatives that are supported
> are:
> > with a different Jenkins TCP/IP port
> > ===========================================
> >
> > -By default the Fuego uses TCP/IP port 8090, but this can be changed to
> another port. This can be used to avoid a conflict with a service
> > already using port 8090 on your host machine, or so that multiple
> instances of Fuego can be run simultaneously.
> > +By default the Fuego uses TCP/IP port 8090, but this can be changed to
> > +another port. This can be used to avoid a conflict with a service
> > +already using port 8090 on your host machine, or so that multiple
> > +instances of Fuego can be run simultaneously.
> >
> > -To use a different port than 8090 for Jenkins, specify it after the
> image name on the command line when you run install.sh. Note that this
> > means that you must specify a Docker image name in order to specify a
> non-default port. For example: ::
> > +To use a different port than 8090 for Jenkins, specify it after the
> > +image name on the command line when you run install.sh. Note that this
> > +means that you must specify a Docker image name in order to specify a
> > +non-default port. For example: ::
> >
> >
> > $ ./install.sh fuego 7777
> >
> >
> > -This would install Fuego, with an docker image name of 'fuego', a
> docker container name of 'fuego-container', and with Jenkins
> > configured to run on port 7777
> > +This would install Fuego, with an docker image name of 'fuego', a
> > +docker container name of 'fuego-container', and with Jenkins
> > +configured to run on port 7777
> >
> > without Jenkins
> > ==================
> >
> > -Some Fuego users have their own front-ends or back-ends, and don't need
> to
> > -use the Jenkins CI server to control Fuego tests, or visualize Fuego
> test
> > -results. ``install.sh`` supports the option '--nojenkins' which
> produces a docker container without the Jenkins server. This reduces the
> > overhead of the docker container by quite a bit, for those users.
> > -
> > -Inside the docker container, the Fuego core is still available.
> Boards, toolchains, and tests are configured normally, but the 'ftc' command
> > line
> > -tool is used to execute tests. There is no need to use any of the 'ftc'
> > -functions to manage nodes, jobs or views in the Jenkins system. 'ftc'
> > -is used to directly execute tests using 'ftc run-test', and results can
> be
> > -queried using 'ftc list-runs' and 'ftc gen-report'.
> > -
> > -When using Fuego with a different results visualization backend, the
> user will
> > -use 'ftc put-run' to send the test result data to the configured back
> end.
> > +Some Fuego users have their own front-ends or back-ends, and don't
> > +need to use the Jenkins CI server to control Fuego tests, or visualize
> > +Fuego test results. ``install.sh`` supports the option '--nojenkins'
> > +which produces a docker container without the Jenkins server. This
> > +reduces the overhead of the docker container by quite a bit, for those
> > +users.
> > +
> > +Inside the docker container, the Fuego core is still available.
> > +Boards, toolchains, and tests are configured normally, but the 'ftc'
> > +command line tool is used to execute tests. There is no need to use
> > +any of the 'ftc' functions to manage nodes, jobs or views in the
> > +Jenkins system. 'ftc' is used to directly execute tests using 'ftc
> > +run-test', and results can be queried using 'ftc list-runs' and 'ftc
> > +gen-report'.
> > +
> > +When using Fuego with a different results visualization backend, the
> > +user will use 'ftc put-run' to send the test result data to the
> > +configured back end.
> >
> > without a container
> > ===========================
> >
> > -Usually, for security and test reproducibility reasons, Fuego is
> executed inside a docker container on your host machine. That is, the
> > default installation of Fuego will create a docker container using all
> the software that is needed for Fuego's tests.
> > -However, in some configurations it is desirable to execute Fuego
> directly on a host machine (not inside a docker container). A user may
> > have a dedicated machine, or they may want to avoid the overhead of
> running a docker container.
> > -
> > -A separate install script, called 'install-debian.sh' can be used in
> place
> > -of 'install.sh' to install the Fuego system onto a Debian-based Linux
> distribution.
> > -
> > -Please note that installing without a container is not advised unless
> you know exactly what you are doing. In this configuration, Fuego will
> > not be able to manage host-side test dependencies for you correctly.
> > -
> > -Please note also that executing without a container presents a possible
> > -security risk for your host. Fuego tests can run arbitrary bash
> > -instruction sequences as part of their execution. So there is a danger
> when running tests from unknown third parties that they will
> > execute something on your test host that breaches the security, or that
> inadvertently damages
> > -you filesystem or data.
> > -
> > -However, despite these drawbacks, there are test scenarios (such as
> installing
> > -Fuego directly to a target board), where this configuration makes sense.
> > +Usually, for security and test reproducibility reasons, Fuego is
> > +executed inside a docker container on your host machine. That is, the
> > +default installation of Fuego will create a docker container using all
> > +the software that is needed for Fuego's tests. However, in some
> > +configurations it is desirable to execute Fuego directly on a host
> > +machine (not inside a docker container). A user may have a dedicated
> > +machine, or they may want to avoid the overhead of running a docker
> > +container.
> > +
> > +A separate install script, called 'install-debian.sh' can be used in
> > +place of 'install.sh' to install the Fuego system onto a Debian-based
> > +Linux distribution.
> > +
> > +Please note that installing without a container is not advised unless
> > +you know exactly what you are doing. In this configuration, Fuego will
> > +not be able to manage host-side test dependencies for you correctly.
> > +
> > +Please note also that executing without a container presents a
> > +possible security risk for your host. Fuego tests can run arbitrary
> > +bash instruction sequences as part of their execution. So there is a
> > +danger when running tests from unknown third parties that they will
> > +execute something on your test host that breaches the security, or
> > +that inadvertently damages you filesystem or data.
> > +
> > +However, despite these drawbacks, there are test scenarios (such as
> > +installing Fuego directly to a target board), where this configuration
> > +makes sense.
> >
> >
> >
>
> That's all for today. I ran out of time, but I will continue reviewing
> the patch material
> and making convention recommendations tomorrow.
> -- Tim
>
>
--
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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.linuxfoundation.org/pipermail/fuego/attachments/20200925/16f5e276/attachment-0001.html>
More information about the Fuego
mailing list