Skip to content

Commit e355ab2

Browse files
mtemplingmtempling
committed
Initial revision
1 parent 5941368 commit e355ab2

16 files changed

+4813
-2
lines changed

‎README.md

+255-2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,255 @@
1-
# ove
2-
OVE gathers git repositories and the knowledge how to build and test them
1+
![OVE](ove.png)
2+
3+
# OVE
4+
OVE is gathering git repositories and the knowledge how to build and test them.
5+
6+
The OVE environment justification: To have a localized yet versioned top
7+
source view to enable fast modify-build-test loops for developers or anyone
8+
that prefers a see-the-big-picture approach or simply want to take quick peek.
9+
10+
## Terminology
11+
OVE is dependent on one top git repository (OWEL). This top repository keep track of three things:
12+
13+
* Git repositories and revisions. Specified in a text file '**revtab**'.
14+
15+
* Projects. A project is typically something that creates a library or executable. Projects has their own build system - OVE does not care which one. It's up to you to decide how to define the project structure. OVE keep track of project dependencies and know in what order to build individual projects. Projects are defined in a YAML file '**projs**'. Individual build steps (bootstrap, configure, build, install) is defined in separate executable files at this location: '**projects/<name/**'.
16+
17+
* System tests. Tests are defined in a text file **systests** and groups of tests (test suites) are defined in **systest-groups**.
18+
19+
The next section will explain the above in more detail.
20+
21+
### revtab
22+
A text file that contains four fields:
23+
24+
* name: Unique identifier of the git repository. Characters allowed: a-z, A-Z and underscore
25+
* fetch URL: The fetch URL.
26+
* push URL: The pull URL. Not used.
27+
* revision: The git revision. This is passed on to 'git checkout'.
28+
29+
Example:
30+
31+
$ cat revtab
32+
# name fetch URL push URL revision
33+
repoX ssh://xyz/repoX ssh://xyz/repoX master
34+
deps/repoY ssh://xyz/repoY ssh://xyz/repoY master
35+
36+
### projs
37+
A YAML file that contains a list of projects with the following syntax:
38+
39+
name:
40+
deps: list of projects that need to be built before myself
41+
needs: list of packages that need to be installed before I can be built
42+
path: path to the source code of myself
43+
version: Optional. Passed on to all build stages for this project.
44+
45+
Example:
46+
47+
$ cat projs
48+
---
49+
projA:
50+
deps: projB
51+
needs: autoconf automake g++
52+
path: repoX
53+
54+
projB:
55+
deps: projC
56+
needs: build-essential
57+
path: repoY
58+
59+
projC:
60+
needs: build-essential
61+
path: repoY
62+
63+
### systests and systests-groups
64+
'systests' is a text file that contains a list of tests. One row is one test:
65+
66+
* name: Unique identifier for the test
67+
* timeout: time in seconds when the test should finish
68+
* type: 0 = normal. 1 = will break execution on failures if this test is part of a test suite.
69+
* path: where to execute the test
70+
* command: command to execute
71+
72+
Example:
73+
74+
$ cat systests
75+
# name timeout (s) type path command
76+
# ----------------------------------------------
77+
t1 5 0 repoX "sleep 4"
78+
t2 1 0 repoX "echo Hello"
79+
t3 3600 0 repoY "./long-duration-test
80+
81+
'systests-groups' is a YAML file that contains groups/sets of tests. Example:
82+
83+
$ cat systests-groups
84+
all:
85+
- t1
86+
- t2
87+
- t3
88+
sanity:
89+
- t1
90+
91+
## Setup
92+
One OVE project is typically setup using the following oneliner:
93+
94+
$ curl -sSL https://raw.githubusercontent.com/Ericsson/ove/master/setup | bash -s <name> <OWEL>
95+
96+
* name: Path to the OVE workspace.
97+
* OWEL: URL of the top git repository
98+
99+
The setup script will basically do two things:
100+
101+
* create the **name** directory
102+
* clone the OVE and OWEL git repositories
103+
104+
The '**setup**' script will now tell you to run the '**source ove**' command. Here, OVE will do a check that you have the required programs installed on your machine. This is the current list:
105+
106+
* column
107+
* file
108+
* envsubst
109+
* git
110+
* hostname
111+
* pgrep
112+
* script
113+
* tree
114+
* tsort
115+
116+
OVE is also dependent on 'sed/grep/tail/awk/...' but they are not (yet) checked for.
117+
118+
### Setup example
119+
120+
$ curl -sSL https://raw.githubusercontent.com/Ericsson/ove/master/setup | bash -s abc ssh://github.com/Ericsson/ove-tutorial
121+
Cloning into '.ove'...
122+
Cloning into 'xyz'...
123+
...
124+
$ cd abc
125+
$ source ove
126+
OVE [SHA-1: ... @ Ubuntu 19.10]
127+
This script will do a few things:
128+
129+
* add 39 bash variables:
130+
...
131+
132+
* add 75 bash functions:
133+
...
134+
135+
* enable tab completion for ove
136+
137+
Now what? Run 'ove fetch' to sync with the outside world or 'ove help' for more information
138+
139+
$ ove fetch
140+
Cloning into 'repoX'...
141+
Cloning into 'repoY'...
142+
...
143+
repoX ## master..origin/master
144+
repoY ## master..origin/master
145+
.ove ## master..origin/master
146+
147+
$ tree
148+
├── ove -> .ove/ove
149+
├── .ove/
150+
│ ├── .git/
151+
│ ├── LICENSE
152+
│ ├── ove
153+
│ ├── ove.png
154+
│ ├── README.md
155+
│ ├── scripts/
156+
│ ├── setup
157+
│ ├── tests/
158+
│ └── yex
159+
├── .owel -> xyz/
160+
├── repoX/
161+
│ ├── .git/
162+
│ └── README
163+
├── repoY/
164+
│ ├── .git/
165+
│ └── README
166+
└── xyz/
167+
├── .git/
168+
├── projects/
169+
│ ├── projA/
170+
│ │ ├── bootstrap
171+
│ │ ├── build
172+
│ │ ├── configure
173+
│ │ └── install
174+
│ ├── projB/
175+
│ │ ├── bootstrap
176+
│ │ ├── build
177+
│ │ ├── configure
178+
│ │ └── install
179+
│ └── projC/
180+
│ ├── bootstrap
181+
│ ├── build
182+
│ ├── configure
183+
│ └── install
184+
├── projs
185+
├── revtab
186+
├── systests
187+
└── systests-groups
188+
189+
## Commands
190+
OVE will enhance (or mess up?) your bash shell with some new commands. We divide them into three categories:
191+
192+
* High level git commands
193+
* Build related commands
194+
* Misc commands
195+
196+
### High level git commands
197+
OVE implements a subset of the "high level" git commands. The OVE version of these commands executes these git commands on all (or selective) **revtab** repositories. Here's a list of implemented git commands:
198+
199+
* add
200+
* apply
201+
* blame
202+
* branch
203+
* checkout
204+
* commit
205+
* describe
206+
* diff
207+
* fetch
208+
* grep
209+
* pull
210+
* show
211+
* status
212+
* tag
213+
214+
### Build related commands
215+
This is a list of build related commands:
216+
217+
* buildme / buildme-parallel
218+
* make
219+
* mrproper
220+
221+
The above list will be dynamically populated with project commands found under the "projects/<proj>/" directories. So, for a "normal" OVE project, these commands are usually also present:
222+
223+
* bootstrap
224+
* configure
225+
* build
226+
* install
227+
228+
Note: For each project command there is a "<command>-parallel" version of that command.
229+
230+
### Misc commands
231+
Here's a list (not complete) of a few Misc commands:
232+
233+
| Command | Description |
234+
|--------------------------|----------------------------------------------------------|
235+
| forall/forall-parallel | run an arbitrary command for all git repositories |
236+
| forowel/forowel-parallel | run an arbitrary command in all OVE projects on the host |
237+
| locate | list OVE projects/workspaces on this host |
238+
| news | view upstream news for each git repository |
239+
| switch | switch to another OVE project |
240+
| unsource | clean up all OVE vars/funcs from this shell |
241+
| vi | open all modified files in 'vi' |
242+
243+
## Tested Linux distributions
244+
* Alpine Linux 3.9.0
245+
* Arch Linux
246+
* Centos
247+
* Debian GNU/Linux 9
248+
* Fedora 29
249+
* Gentoo
250+
* Ubuntu 16.04
251+
* Ubuntu 18.04
252+
* Ubuntu 19.10
253+
254+
## Need more help?
255+
Try 'ove help'.

0 commit comments

Comments
 (0)