source: rtems-central/README.md @ d3edaca

Last change on this file since d3edaca was e49c759, checked in by Sebastian Huber <sebastian.huber@…>, on Jul 15, 2020 at 8:04:25 AM

Rename "rtemsqual" in "rtemsspec"

  • Property mode set to 100644
File size: 4.8 KB
Line 
1# RTEMS Specification Items and Qualification Tools
2
3This repository contains a prototype of the RTEMS specification and tools to
4generate content from the specification.  It demonstrates the use of Python
5development tools such as yapf, flake8, mypy, pylint, pytest, and coverage.
6
7## Repository Overview
8
9* env - contains the Python environment (created by `make env`)
10
11* spec - contains the specification items
12
13* rtemsspec - contains the `rtemsspec` Python package
14
15  * tests - contains Python unit tests
16
17* modules - contains Git submodules
18
19  * rsb - contains the RTEMS Source Builder as a Git submodule
20
21  * rtems - contains the RTEMS sources as a Git submodule
22
23  * rtems-docs - contains the RTEMS documentation sources as a Git submodule
24
25* `rtems_spec_to_x.py` - a command line tool to generate content from the
26  specification
27
28## Getting Started
29
30Copy the sanity check script at least to the pre-push hook (optional also to
31the pre-commit hook):
32```
33cp git-hooks/sanity-check.sh .git/hooks/pre-push
34```
35Run
36```
37git submodule init
38git submodule update
39```
40to initialize the Git submodules.  Run
41```
42make env
43```
44to set up the Python environment.  Activate the Python environment afterwards
45with
46```
47. env/bin/activate
48```
49If submodule URLs changed after a pull use
50```
51git submodule sync
52```
53to activate the new URLs.
54
55## Specification Items
56
57The
58[specification items](https://docs.rtems.org/branches/master/eng/req-eng.html#specification-items)
59are located in the `spec` directory.  You can use a text editor to work with
60them.
61
62## Specification-To-X Tool
63
64The command line tool `rtems_spec_to_x.py` generates content from the
65specification.  The tool is configured by the `config.ini` configuration file.
66This is a prototype implementation.  It demonstrates the generation of a
67project-wide glossary (`external/rtems-docs/c-user/glossary.rst`) and
68document-specific glossaries (`external/rtems-docs/eng/glossary.rst`) from
69glossary specification items (glossary groups and terms in `spec/glos`).
70
71Example:
72```
73$ ./rtems_spec_to_x.py
74$ git status
75On branch master
76Your branch is up to date with 'origin/master'.
77
78nothing to commit, working tree clean
79$ sed -i 's/Binary/Boom/' spec/glos/term/abi.yml
80$ ./rtems_spec_to_x.py
81$ git status
82On branch master
83Your branch is up to date with 'origin/master'.
84
85Changes not staged for commit:
86  (use "git add <file>..." to update what will be committed)
87  (use "git checkout -- <file>..." to discard changes in working directory)
88  (commit or discard the untracked or modified content in submodules)
89
90        modified:   external/rtems-docs (modified content)
91        modified:   spec/glos/term/RTEMS-GLOS-TERM-ABI.yml
92
93no changes added to commit (use "git add" and/or "git commit -a")
94$ cd external/rtems-docs
95$ git diff
96diff --git a/c-user/glossary.rst b/c-user/glossary.rst
97index d0996e8..dfac60c 100644
98--- a/c-user/glossary.rst
99+++ b/c-user/glossary.rst
100@@ -10,7 +10,7 @@ Glossary
101     :sorted:
102 
103     ABI
104-        An acronym for Application Binary Interface.
105+        An acronym for Application Boom Interface.
106 
107     active
108         A term used to describe an object which has been created by an
109diff --git a/eng/glossary.rst b/eng/glossary.rst
110index c58e67f..ac2c8f8 100644
111--- a/eng/glossary.rst
112+++ b/eng/glossary.rst
113@@ -9,7 +9,7 @@ Glossary
114     :sorted:
115 
116     ABI
117-        An acronym for Application Binary Interface.
118+        An acronym for Application Boom Interface.
119 
120     API
121         An acronym for Application Programming Interface.
122```
123
124## Unit Tests and Static Analysers
125
126Run the unit tests and static analysers with:
127```
128make
129```
130You can get a branch coverage report with:
131```
132$ make coverage-report
133coverage report -m --include=...
134Name                      Stmts   Miss Branch BrPart  Cover   Missing
135---------------------------------------------------------------------
136rtemsspec/__init__.py         8      0      0      0   100%
137rtemsspec/applconfig.py     130      0     53      0   100%
138rtemsspec/build.py           36      0     14      0   100%
139rtemsspec/content.py        133      0     44      0   100%
140rtemsspec/glossary.py        70      0     31      0   100%
141rtemsspec/items.py          139      0     46      0   100%
142rtemsspec/util.py            26      0      2      0   100%
143---------------------------------------------------------------------
144TOTAL                       542      0    190      0   100%
145```
146
147## Contributing
148
149Please read
150[Support and Contributing](https://docs.rtems.org/branches/master/user/support/index.html).
151
152For the ESA activity do not push to the `esa` branch directly.  Instead always
153work on topic branches and use merge requests, for example:
154```
155git push -o merge_request.create topic-branch
156```
157
158## License
159
160This project is licensed under the
161[BSD-2-Clause](https://spdx.org/licenses/BSD-2-Clause.html) or
162[CC-BY-SA-4.0](https://spdx.org/licenses/CC-BY-SA-4.0.html).
Note: See TracBrowser for help on using the repository browser.