summaryrefslogtreecommitdiffstats
path: root/README.md
blob: 6c0a69e303fb6823708c8005ebbf833c972ddd8b (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
# RTEMS Specification Items and Qualification Tools

This repository contains a prototype of the RTEMS specification and tools to
generate content from the specification.  It demonstrates the use of Python
development tools such as yapf, flake8, mypy, pylint, pytest, and coverage.

## Repository Overview

* env - contains the Python environment (created by `make env`)

* spec - contains the specification items

* rtemsspec - contains the `rtemsspec` Python package

  * tests - contains Python unit tests

* modules - contains Git submodules

  * rsb - contains the RTEMS Source Builder as a Git submodule

  * rtems - contains the RTEMS sources as a Git submodule

  * rtems-docs - contains the RTEMS documentation sources as a Git submodule

* `rtems_spec_to_x.py` - a command line tool to generate content from the
  specification

## Getting Started

Copy the sanity check script at least to the pre-push hook (optional also to
the pre-commit hook):
```
cp git-hooks/sanity-check.sh .git/hooks/pre-push
```
Run
```
git submodule init
git submodule update
```
to initialize the Git submodules.  Run
```
make env
```
to set up the Python environment.  Activate the Python environment afterwards
with
```
. env/bin/activate
```
If submodule URLs changed after a pull use
```
git submodule sync
```
to activate the new URLs.

## Specification Items

The
[specification items](https://docs.rtems.org/branches/master/eng/req-eng.html#specification-items)
are located in the `spec` directory.  You can use a text editor to work with
them.

## Specification-To-X Tool

The command line tool `rtems_spec_to_x.py` generates content from the
specification.  The tool is configured by the `config.ini` configuration file.
This is a prototype implementation.  It demonstrates the generation of a
project-wide glossary (`external/rtems-docs/c-user/glossary.rst`) and
document-specific glossaries (`external/rtems-docs/eng/glossary.rst`) from
glossary specification items (glossary groups and terms in `spec/glos`).

Example:
```
$ ./rtems_spec_to_x.py
$ git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean
$ sed -i 's/Binary/Boom/' spec/glos/term/abi.yml
$ ./rtems_spec_to_x.py
$ git status
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)
  (commit or discard the untracked or modified content in submodules)

        modified:   external/rtems-docs (modified content)
        modified:   spec/glos/term/RTEMS-GLOS-TERM-ABI.yml

no changes added to commit (use "git add" and/or "git commit -a")
$ cd external/rtems-docs
$ git diff
diff --git a/c-user/glossary.rst b/c-user/glossary.rst
index d0996e8..dfac60c 100644
--- a/c-user/glossary.rst
+++ b/c-user/glossary.rst
@@ -10,7 +10,7 @@ Glossary
     :sorted:
 
     ABI
-        An acronym for Application Binary Interface.
+        An acronym for Application Boom Interface.
 
     active
         A term used to describe an object which has been created by an
diff --git a/eng/glossary.rst b/eng/glossary.rst
index c58e67f..ac2c8f8 100644
--- a/eng/glossary.rst
+++ b/eng/glossary.rst
@@ -9,7 +9,7 @@ Glossary
     :sorted:
 
     ABI
-        An acronym for Application Binary Interface.
+        An acronym for Application Boom Interface.
 
     API
         An acronym for Application Programming Interface.
```

## Unit Tests and Static Analysers

Run the unit tests and static analysers with:
```
make
```
You can get a branch coverage report with:
```
$ make coverage-report 
coverage report -m --include=...
Name                      Stmts   Miss Branch BrPart  Cover   Missing
---------------------------------------------------------------------
rtemsspec/__init__.py         8      0      0      0   100%
rtemsspec/applconfig.py     130      0     53      0   100%
rtemsspec/build.py           36      0     14      0   100%
rtemsspec/content.py        133      0     44      0   100%
rtemsspec/glossary.py        70      0     31      0   100%
rtemsspec/items.py          139      0     46      0   100%
rtemsspec/util.py            26      0      2      0   100%
---------------------------------------------------------------------
TOTAL                       542      0    190      0   100%
```

## Contributing

Please read
[Support and Contributing](https://docs.rtems.org/branches/master/user/support/index.html).

For the ESA activity do not push to the `esa` branch directly.  Instead always
work on topic branches and use merge requests, for example:
```
git push -o merge_request.create topic-branch
```

## License

This project is licensed under the
[BSD-2-Clause](https://spdx.org/licenses/BSD-2-Clause.html) or
[CC-BY-SA-4.0](https://spdx.org/licenses/CC-BY-SA-4.0.html).