Return-Path: DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pathpartnertech.com; s=google; h=mime-version:from:to:cc:subject:date:message-id; bh=ml5JC4eOfyl7Zfc32TkKMF2gJ1cPwUr3tE2/28azGq4=; b=ZBAOaFX4ivzHvDggd7TOLtNkhEbEZvauALtU6QNnhuYPYdMvaPyLt76ZkXGs1XSGr8 1BpUHW72FymbBa0kKZc1NtqJ9BK+DT1ouvn0ohzS7Vi7MFeRifi9BVq7SF/8SBr9uzyI t4XmvPeKir04dKpl9npAxMXuCAz9If/3ojxelP2nt5l97FczhPDMZxI0MHIhDtdoHDCF i2vtPulWfw1SDwIuuJpWrELlE+7+hx6CtnHeLUDgkDwvvIBwiorVTtDy3m5zPsHO15ci 6NEclSS/QUJP9wzclchV61/bhhBVcmfuaZWbrDcYTkKGU3h6r/xS9o0KHa6GVqRa8k5C P3KQ== MIME-Version: 1.0 From: Pooja Date: Wed, 25 Nov 2020 11:44:51 +0530 Message-Id: <1606284891-27888-1-git-send-email-pooja.sm@pathpartnertech.com> Content-Type: text/plain; charset="US-ASCII" Subject: [Fuego] [PATCH] Docs: Convert tbwiki pages into .rst files List-Id: Mailing list for the Fuego test framework List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: tbird20d@yahoo.com, Tim.Bird@sony.com Cc: fuego@lists.linuxfoundation.org, Pooja More From: Pooja More Following pages are converted: Coding_style.rst Fuego_directories.rst Glossary.rst Signed-off-by: Pooja More --- 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 %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 + +``_ + + +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 +``_. 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 +``_. 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.`` - log files for a particular test test + + * ``...`` - the 'run' directory + for a test execution + + * ``devlog.txt`` - the developer log for a test - list of operations + executed during the test + * ``syslogs.