1 |
2 |
petebleack |
|
2 |
|
|
|
3 |
|
|
Dirac development practices
|
4 |
|
|
======================
|
5 |
|
|
|
6 |
|
|
Contents
|
7 |
|
|
--------
|
8 |
|
|
|
9 |
|
|
1. Licenses and submitting work
|
10 |
|
|
|
11 |
|
|
2. Sourceforge Developers forum
|
12 |
|
|
|
13 |
|
|
3. Mailing lists
|
14 |
|
|
|
15 |
|
|
4. Using the CVS repository
|
16 |
|
|
|
17 |
|
|
5. CVS log messages
|
18 |
|
|
|
19 |
|
|
6. Design practices
|
20 |
|
|
|
21 |
|
|
7. Line-endings
|
22 |
|
|
|
23 |
|
|
8. Binary files in CVS
|
24 |
|
|
|
25 |
|
|
|
26 |
|
|
|
27 |
|
|
1. Licenses and submitting work
|
28 |
|
|
-------------------------------
|
29 |
|
|
|
30 |
|
|
Developers submitting work to the Dirac project should print out,
|
31 |
|
|
complete, and sign the Developer's Certificate of Origin contained
|
32 |
|
|
in the DCO.developers file. It should be posted to:
|
33 |
|
|
|
34 |
|
|
Dr Tim Borer
|
35 |
|
|
BBC Research and Development
|
36 |
|
|
Kingswood Warren
|
37 |
|
|
Tadworth
|
38 |
|
|
Surrey KT20 6NP
|
39 |
|
|
United Kingdom
|
40 |
|
|
|
41 |
|
|
For simplicity developers must submit code using the same
|
42 |
|
|
license that we distribute under, which is the Mozilla Triple
|
43 |
|
|
license (http://www.mozilla.org/MPL/). Using any other license
|
44 |
|
|
causes complexity and FUD.
|
45 |
|
|
|
46 |
|
|
Contributions should be in the form of a patch, which may be for a
|
47 |
|
|
whole directory. For changes to an existing file all that is needed
|
48 |
|
|
is to add the author's name to the list of contributors, since the
|
49 |
|
|
license will remain the MPL. For new files, the header in each file
|
50 |
|
|
should be completed from Exhibit A, the Mozilla Triple License (from the
|
51 |
|
|
COPYING file). It should NOT be copied from files already obtained
|
52 |
|
|
in the Dirac project, since some details may differ.
|
53 |
|
|
|
54 |
|
|
To create a context diff patch run the command
|
55 |
|
|
|
56 |
|
|
diff -ruN compress-orig compress-mods > patch.txt
|
57 |
|
|
|
58 |
|
|
where compress-orig is the directory with the original code and
|
59 |
|
|
compress-mods is the directory with the modified files.
|
60 |
|
|
|
61 |
|
|
The patch.txt file should then be submitted to the Sourceforge Patch
|
62 |
|
|
tracker.
|
63 |
|
|
|
64 |
|
|
2. Sourceforge Developers forum
|
65 |
|
|
-------------------------------
|
66 |
|
|
The Developers forum is where Dirac core developers plan and coordinate
|
67 |
|
|
changes to Dirac. All API changes, new features and implementation
|
68 |
|
|
difficulties are announced and discussed here.
|
69 |
|
|
|
70 |
|
|
Examples of changes which should be announced in the Developers forum:
|
71 |
|
|
|
72 |
|
|
- Pic API change: return bool instead of void for ReadNextFrame
|
73 |
|
|
- Pic API change: most methods can now throw ErrorState objects
|
74 |
|
|
|
75 |
|
|
Changes which are small in scope and unlikely to affect developers
|
76 |
|
|
should not be announced on the forum. Changes which touch
|
77 |
|
|
many files can fall into this category - for example
|
78 |
|
|
|
79 |
|
|
- Fixed inconsistent CRLF line-endings to be LF.
|
80 |
|
|
- Fixed "use of uninitialised variable" cases found by gcc.
|
81 |
|
|
- Fixed memory leak in all instantiations of Pic (found by valgrind).
|
82 |
|
|
- Add feature test for stdint.h to be portable to Solaris.
|
83 |
|
|
|
84 |
|
|
Developers should 'monitor' the forums by going to the forum page and
|
85 |
|
|
clicking 'Monitor this forum'. Any new message will then be emailed
|
86 |
|
|
to their username@users.sourceforge.net email address.
|
87 |
|
|
http://sourceforge.net/forum/forum.php?forum_id=353620
|
88 |
|
|
|
89 |
|
|
|
90 |
|
|
3. Mailing lists
|
91 |
|
|
----------------
|
92 |
|
|
Developers should subscribe to the dirac-announce and dirac-commits
|
93 |
|
|
mailing lists. dirac-announce is used to announce new releases and
|
94 |
|
|
dirac-commits is sent mail automatically for every commit.
|
95 |
|
|
|
96 |
|
|
|
97 |
|
|
4. Using the CVS repository
|
98 |
|
|
---------------------------
|
99 |
|
|
|
100 |
|
|
The latest (but non-stable) version of the code can be downloaded direct
|
101 |
|
|
from the Sourceforge repository using anonymous CVS. Instructions for
|
102 |
|
|
doing so can be found at the Dirac CVS page:
|
103 |
|
|
|
104 |
|
|
http://sourceforge.net/cvs/
|
105 |
|
|
|
106 |
|
|
The Dirac codec module is called 'diracvhdl'.
|
107 |
|
|
|
108 |
|
|
5. CVS log messages
|
109 |
|
|
-------------------
|
110 |
|
|
Always indicate why the change is necessary in addition to a succinct summary
|
111 |
|
|
of what as changed. As the number of developers increases it becomes
|
112 |
|
|
increasingly difficult for developers to understand the changes going on in
|
113 |
|
|
areas they are not familiar with. If the changes relate to an API change
|
114 |
|
|
developers may not realise this if it is not mentioned in the log message
|
115 |
|
|
as the reason for the change.
|
116 |
|
|
|
117 |
|
|
E.g.
|
118 |
|
|
Bad
|
119 |
|
|
---
|
120 |
|
|
- Added gamma parameter
|
121 |
|
|
- Replace stricmp with strcasecmp
|
122 |
|
|
|
123 |
|
|
Good
|
124 |
|
|
----
|
125 |
|
|
- Added gamma parameter to record more accurate data on source material
|
126 |
|
|
- Enhanced portability: stricmp replaced by strcasecmp (the POSIX standard)
|
127 |
|
|
|
128 |
|
|
|
129 |
|
|
6. Design practices
|
130 |
|
|
---------------------
|
131 |
|
|
|
132 |
|
|
I. Coding Style
|
133 |
|
|
|
134 |
|
|
The following guidelines must be adhered to while developing code.
|
135 |
|
|
|
136 |
|
|
-- CVS related tags
|
137 |
|
|
|
138 |
|
|
- Include the following RCS tags in all new files (.vhd). Include them
|
139 |
|
|
on the first line of the licence block
|
140 |
|
|
|
141 |
|
|
Id
|
142 |
|
|
Name
|
143 |
|
|
|
144 |
|
|
E.g.
|
145 |
|
|
-- /* ***** BEGIN LICENSE BLOCK *****
|
146 |
|
|
-- *
|
147 |
5 |
petebleack |
-- * $Id: README.developers,v 1.2 2005-05-27 16:00:27 petebleackley Exp $ $Name: not supported by cvs2svn $
|
148 |
2 |
petebleack |
-- *
|
149 |
|
|
-- * rest of licence text
|
150 |
|
|
-- * ***** END LICENSE BLOCK ***** */
|
151 |
|
|
|
152 |
|
|
|
153 |
|
|
- Remove the following tags from all files. Do not include them in new files
|
154 |
|
|
Author
|
155 |
|
|
Revision
|
156 |
|
|
Log
|
157 |
|
|
|
158 |
|
|
-- General Source code formatting
|
159 |
|
|
|
160 |
|
|
All signals should be std_logic or std_logic_vector.
|
161 |
|
|
Widths and slices of vectors should be specified with downto.
|
162 |
|
|
VHDL '97 style is preferred for end statements (e.g. end architecture RTL;)
|
163 |
5 |
petebleack |
VHDL keywords should be in lower case, entity, architecture and signal names, and other user-defined names in upper case
|
164 |
|
|
When instantiating a component, use both positional association and named association, ie the "belt and braces" approach.
|
165 |
2 |
petebleack |
|
166 |
|
|
|
167 |
|
|
|
168 |
|
|
III. Code Review
|
169 |
|
|
|
170 |
|
|
All code will be peer-reviewed before being checked in to SourceForge
|
171 |
|
|
CVS. Developers should use the guidelines specified in the Coding Style
|
172 |
|
|
sub-section while reviewing code.
|
173 |
|
|
|
174 |
|
|
7. Line-endings
|
175 |
|
|
---------------
|
176 |
|
|
All source code and documentation will have LF line-endings, include makefiles
|
177 |
|
|
and scripts.
|
178 |
|
|
|
179 |
|
|
|
180 |
|
|
8. Binary files in CVS
|
181 |
|
|
----------------------
|
182 |
|
|
CVS will modify files during checkin and checkout unless they are tagged as
|
183 |
|
|
binary. The modifications include translation of CR-LF <-> LF (depending on
|
184 |
|
|
the OS of the CVS client) and expansion of CVS keywords such as $Id and $Log.
|
185 |
|
|
|
186 |
|
|
Files which must not be modified in this way must be tagged as binary either
|
187 |
|
|
using the add command or admin command:
|
188 |
|
|
cvs add -kb fig1.jpg
|
189 |
|
|
cvs admin -kb fig1.jpg (for files already in CVS)
|
190 |
|
|
|
191 |
|
|
MS VC++ project files, such as .vcproj and .sln, fall into this category since
|
192 |
|
|
they do not function if their line-endings are not CR-LF.
|
193 |
|
|
|
194 |
5 |
petebleack |
------------------------------------------------------------------------
|