-
Notifications
You must be signed in to change notification settings - Fork 19
/
HACKING
121 lines (91 loc) · 4.66 KB
/
HACKING
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
BUG REPORTS
===========
Try to describe the circumstances as exactly as possible. Are you using
extra omxplayer options with the O commend? Don't forget to mention it.
Also look at the /var/log/omxlog logfile and send relevant details.
If you modify the source of omxd and run into problems, don't create an
issue pretending it's a bug. I've had multiple cases of long
discussions about bugs, until eventually it turned out people are running
their modified code. This is evil and rude and wasting my time.
If you want help with your development efforts, state in the very
first sentence of the issue that you're running modified code.
What's even better, send a pull request with your changes. That way
I'll have a chance to help you. Don't be ashamed of your horrible,
buggy, tasteless, unreadable code. Publishing it is a much better
option than lying to me and wasting my time.
CODING STYLE
============
Please use a variant of K&R, the Linux Coding Style:
https://www.kernel.org/doc/Documentation/CodingStyle
In short: indent by tabs and display your tabs as 8 spaces.
Functions should fit in a 80x50 box. Combined with Tabs this also stops the
"nesting hell".
Also you can use C99 features, like variable declarations anywhere.
Please keep the declarations as close to the actual usage as possible.
But DO NOT use C99's bool datatype. It's evil. C is a portable assembler,
and you should be able to tell a size of each datatype easily, so keep
your abstract shit away. Also how do you serialize a bool? "true" is a string
and 1 is a number (Welcome to my spaceship). And I did not even mention
the chaos when people start comparing variables with true and false.
Just say no to booleans. There are no booleans in K&R.
COMMITS
=======
The first line of commit messages shall summarize the change in 50 characters,
include an issue id (like #19) at the end of line if relevant.
Additional details, if any, should follow after a blank line.
Use headlinese style: http://en.wikipedia.org/wiki/Headlinese
Use imperative, otherwise people don't know if it describes the bug or the fix.
Add the important stuff, leave out the fluff. Using words like "project",
"omxd", "update" and "issue" is almost certainly wrong.
Each commit should be about one single change. For a big change, use a feature
branch and several small commits.
LIBRARIES
=========
I hate libraries. I don't even use printf() because it's an unpredictable piece
of bloatware. Don't introduce getopt for Heaven's sake. I already have a dead
simple loop for argv[].
SHARED LIBRARIES
================
If you've still convinced me to introduce your cool indispensable library,
and you've also included the deb package related changes in your pull request,
please make sure you link the library statically. Shared libs are mostly evil,
the current trend of containers is also mostly a cure for them.
DBUS
====
Do not, under any circumstances, send me Dbus related issues or pull requests.
I do not deal with Dbus. If you interfere with the Dbus interface of
omxplayer instances started by omxd, you're on your own. I absolutely and
positively refuse to help.
TECHNICAL DETAILS
=================
The /var/run/omxctl FIFO and the protocol
-----------------------------------------
As opposed to a socket, you can simply echo a command into a FIFO file.
And the protocol is dead simple: one-letter command plus optional filename.
The trick with FIFOs:
open() for read blocks until someone opens it for write.
open() for write blocks until soemone opens it for read.
writedec(), writestr(), printfd(), sscand(), WTF?
-------------------------------------------------
The similar C-library calls all come with unnecessary complication and, worse,
user-space buffering. And it was fun to write these, just using bare syscalls.
Why not store the playlist in memory?
-------------------------------------
Erm... see the next chapter.
Why store the playlist in memory, then ?!
-----------------------------------------
With the advent of the low-gap playback, the playlist returns 2 tracks.
It was much easier to implement with a dynamic in-memory playlist.
The in-file playlist.c was messy enough before, so it was abandoned.
Welcome to the m_list.c in-memory playlist: the list itself is not a
linked list but a dynamic array of pointers to dynamically allocated strings.
A dynamic array is directly addressable and needs an occasional realloc()
instead of many messy malloc() and free() calls.
Timekeeping
-----------
Track time evaluation shall be based on log file entry timestamps:
start: t_play = 0; t_start = t
pause: t_play += t - t_start; paused = 1
play: t_start = t; paused = 0
fFrR: t_play += t - t_start + dt; t_start = t
EOF: t_play += time - t_start unless paused