?rev1line? |
?rev2line? |
|
|
|
|
|
Dirac development practices
|
|
======================
|
|
|
|
Contents
|
|
--------
|
|
|
|
1. Licenses and submitting work
|
|
|
|
2. Sourceforge Developers forum
|
|
|
|
3. Mailing lists
|
|
|
|
4. Using the CVS repository
|
|
|
|
5. CVS log messages
|
|
|
|
6. Design practices
|
|
|
|
7. Line-endings
|
|
|
|
8. Binary files in CVS
|
|
|
|
|
|
|
|
1. Licenses and submitting work
|
|
-------------------------------
|
|
|
|
Developers submitting work to the Dirac project should print out,
|
|
complete, and sign the Developer's Certificate of Origin contained
|
|
in the DCO.developers file. It should be posted to:
|
|
|
|
Dr Tim Borer
|
|
BBC Research and Development
|
|
Kingswood Warren
|
|
Tadworth
|
|
Surrey KT20 6NP
|
|
United Kingdom
|
|
|
|
For simplicity developers must submit code using the same
|
|
license that we distribute under, which is the Mozilla Triple
|
|
license (http://www.mozilla.org/MPL/). Using any other license
|
|
causes complexity and FUD.
|
|
|
|
Contributions should be in the form of a patch, which may be for a
|
|
whole directory. For changes to an existing file all that is needed
|
|
is to add the author's name to the list of contributors, since the
|
|
license will remain the MPL. For new files, the header in each file
|
|
should be completed from Exhibit A, the Mozilla Triple License (from the
|
|
COPYING file). It should NOT be copied from files already obtained
|
|
in the Dirac project, since some details may differ.
|
|
|
|
To create a context diff patch run the command
|
|
|
|
diff -ruN compress-orig compress-mods > patch.txt
|
|
|
|
where compress-orig is the directory with the original code and
|
|
compress-mods is the directory with the modified files.
|
|
|
|
The patch.txt file should then be submitted to the Sourceforge Patch
|
|
tracker.
|
|
|
|
2. Sourceforge Developers forum
|
|
-------------------------------
|
|
The Developers forum is where Dirac core developers plan and coordinate
|
|
changes to Dirac. All API changes, new features and implementation
|
|
difficulties are announced and discussed here.
|
|
|
|
Examples of changes which should be announced in the Developers forum:
|
|
|
|
- Pic API change: return bool instead of void for ReadNextFrame
|
|
- Pic API change: most methods can now throw ErrorState objects
|
|
|
|
Changes which are small in scope and unlikely to affect developers
|
|
should not be announced on the forum. Changes which touch
|
|
many files can fall into this category - for example
|
|
|
|
- Fixed inconsistent CRLF line-endings to be LF.
|
|
- Fixed "use of uninitialised variable" cases found by gcc.
|
|
- Fixed memory leak in all instantiations of Pic (found by valgrind).
|
|
- Add feature test for stdint.h to be portable to Solaris.
|
|
|
|
Developers should 'monitor' the forums by going to the forum page and
|
|
clicking 'Monitor this forum'. Any new message will then be emailed
|
|
to their username@users.sourceforge.net email address.
|
|
http://sourceforge.net/forum/forum.php?forum_id=353620
|
|
|
|
|
|
3. Mailing lists
|
|
----------------
|
|
Developers should subscribe to the dirac-announce and dirac-commits
|
|
mailing lists. dirac-announce is used to announce new releases and
|
|
dirac-commits is sent mail automatically for every commit.
|
|
|
|
|
|
4. Using the CVS repository
|
|
---------------------------
|
|
|
|
The latest (but non-stable) version of the code can be downloaded direct
|
|
from the Sourceforge repository using anonymous CVS. Instructions for
|
|
doing so can be found at the Dirac CVS page:
|
|
|
|
http://sourceforge.net/cvs/
|
|
|
|
The Dirac codec module is called 'diracvhdl'.
|
|
|
|
5. CVS log messages
|
|
-------------------
|
|
Always indicate why the change is necessary in addition to a succinct summary
|
|
of what as changed. As the number of developers increases it becomes
|
|
increasingly difficult for developers to understand the changes going on in
|
|
areas they are not familiar with. If the changes relate to an API change
|
|
developers may not realise this if it is not mentioned in the log message
|
|
as the reason for the change.
|
|
|
|
E.g.
|
|
Bad
|
|
---
|
|
- Added gamma parameter
|
|
- Replace stricmp with strcasecmp
|
|
|
|
Good
|
|
----
|
|
- Added gamma parameter to record more accurate data on source material
|
|
- Enhanced portability: stricmp replaced by strcasecmp (the POSIX standard)
|
|
|
|
|
|
6. Design practices
|
|
---------------------
|
|
|
|
I. Coding Style
|
|
|
|
The following guidelines must be adhered to while developing code.
|
|
|
|
-- CVS related tags
|
|
|
|
- Include the following RCS tags in all new files (.vhd). Include them
|
|
on the first line of the licence block
|
|
|
|
Id
|
|
Name
|
|
|
|
E.g.
|
|
-- /* ***** BEGIN LICENSE BLOCK *****
|
|
-- *
|
|
-- * $Id: README.developers,v 1.2 2005-05-27 16:00:27 petebleackley Exp $ $Name: not supported by cvs2svn $
|
|
-- *
|
|
-- * rest of licence text
|
|
-- * ***** END LICENSE BLOCK ***** */
|
|
|
|
|
|
- Remove the following tags from all files. Do not include them in new files
|
|
Author
|
|
Revision
|
|
Log
|
|
|
|
-- General Source code formatting
|
|
|
|
All signals should be std_logic or std_logic_vector.
|
|
Widths and slices of vectors should be specified with downto.
|
|
VHDL '97 style is preferred for end statements (e.g. end architecture RTL;)
|
|
VHDL keywords should be in lower case, entity, architecture and signal names, and other user-defined names in upper case
|
|
When instantiating a component, use both positional association and named association, ie the "belt and braces" approach.
|
|
|
|
|
|
|
|
III. Code Review
|
|
|
|
All code will be peer-reviewed before being checked in to SourceForge
|
|
CVS. Developers should use the guidelines specified in the Coding Style
|
|
sub-section while reviewing code.
|
|
|
|
7. Line-endings
|
|
---------------
|
|
All source code and documentation will have LF line-endings, include makefiles
|
|
and scripts.
|
|
|
|
|
|
8. Binary files in CVS
|
|
----------------------
|
|
CVS will modify files during checkin and checkout unless they are tagged as
|
|
binary. The modifications include translation of CR-LF <-> LF (depending on
|
|
the OS of the CVS client) and expansion of CVS keywords such as $Id and $Log.
|
|
|
|
Files which must not be modified in this way must be tagged as binary either
|
|
using the add command or admin command:
|
|
cvs add -kb fig1.jpg
|
|
cvs admin -kb fig1.jpg (for files already in CVS)
|
|
|
|
MS VC++ project files, such as .vcproj and .sln, fall into this category since
|
|
they do not function if their line-endings are not CR-LF.
|
|
|
|
------------------------------------------------------------------------
|
