Add a testsuite for libsigrok.

[libsigrok.git] / HACKING

diff --git a/HACKING b/HACKING
index d89f4a32b8ec1a70a8987e1c2021f8c3a57dd322..faac0a8c0da22a4bcf900efa8ccddb87f2703a20 100644 (file)
--- a/HACKING
+++ b/HACKING
@@ -24,6 +24,50 @@ Contributions
    github.com, or any other public git hosting site.
 
 
+Adding a new hardware driver
+----------------------------
+
+The simple, scripted way (recommended):
+---------------------------------------
+
+Use the 'new-driver' script from the sigrok-util repo:
+
+ $ git clone git://sigrok.org/sigrok-util
+ $ cd sigrok-util/source
+ $ ./new-driver "Tondaj SL-814"
+
+The example above generates a patch file against the current libsigrok
+development git tree which adds a simple "stub" driver for your device
+(the Tondaj SL-814 sound level meter in this case).
+
+You can apply it like this:
+
+ $ cd libsigrok
+ $ git am 0001-tondaj-sl-814-Initial-driver-skeleton.patch
+
+You can now edit the files in the hardware/tondaj-sl-814 directory as needed.
+
+
+The manual way:
+---------------
+
+This is a rough overview of what you need to do in order to add a new driver
+(using the Tondaj SL-814 device as example). It's basically what the
+'new-driver' script (see above) does for you:
+
+ - configure.ac:
+   - Add an --enable-tondaj-sl-814 option.
+   - Add "hardware/tondaj-sl-814/Makefile" to the AC_CONFIG_FILES list.
+   - Add and entry for the device in the "Enabled hardware drivers" list
+     at the bottom of the file.
+ - hardware/Makefile.am: Add "tondaj-sl-814" to the SUBDIRS variable.
+ - hwdriver.c: Add a tondaj_sl_814_driver_info entry in two places.
+ - hardware/tondaj-sl-814/ directory: Add the following files:
+   Makefile.am, api.c, protocol.c, protocol.h
+
+See existing drivers or the 'new-driver' output for the details.
+
+
 Random notes
 ------------
 
@@ -71,6 +115,18 @@ Random notes
    should end with "_all", e.g. "_remove_all", "_get_all", and so on.
    Use "_remove_all" in favor of "_clear" for consistency.
 
+ - All enums should generally use an explicit start number of 10000.
+   If there are multiple "categories" in the enum entries, each category
+   should be 10000 entries apart from the next one. The start of categories
+   are thus 10000, 20000, 30000, and so on.
+
+   Adding items to an enum MUST always append to a "category", never add
+   items in the middle of a category. The order of items MUST NOT be changed.
+   Any of the above would break the ABI.
+
+   The enum item 0 is special and is used as terminator in some lists, thus
+   enums should not use this for "valid" entries (and start at 10000 instead).
+
 
 Doxygen
 -------
@@ -88,6 +144,14 @@ Doxygen
    Variables that are "static" don't need to be marked like this.
 
 
+Testsuite
+---------
+
+You can run the libsigrok testsuite using:
+
+ $ make check
+
+
 Release engineering
 -------------------