Don't set _POSIX_C_SOURCE for VXI/RPC related files.

[libsigrok.git] / HACKING

diff --git a/HACKING b/HACKING
index 0e818c2116d718c0703e1dceda4ecd06ed333e10..aa408ffb6cad15c90ca5ecc0250475886b94a9e4 100644 (file)
--- a/HACKING
+++ b/HACKING
@@ -45,7 +45,7 @@ You can apply it like this:
  $ cd libsigrok
  $ git am 0001-tondaj-sl-814-Initial-driver-skeleton.patch
 
  $ 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
+You can now edit the files in src/hardware/tondaj-sl-814 as needed

 and implement your driver based on the skeleton files there. That means your
 patch submission later will consist of at least two patches: the initial one
 adding the skeleton driver, and one or more additional patches that actually
 and implement your driver based on the skeleton files there. That means your
 patch submission later will consist of at least two patches: the initial one
 adding the skeleton driver, and one or more additional patches that actually


@@ -59,15 +59,10 @@ 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:
 
 (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
+ - Makefile.am: Add HW_TONDAJ_SL_814 and add to libsigrok_la_SOURCES.
+ - configure.ac: Add a DRIVER() and DRIVER2() call.
+ - src/drivers.c: Add a tondaj_sl_814_driver_info entry in two places.
+ - src/hardware/tondaj-sl-814/ directory: Add api.c, protocol.c, protocol.h.

 
 See existing drivers or the 'new-driver' output for the details.
 
 
 See existing drivers or the 'new-driver' output for the details.
 


@@ -81,18 +76,21 @@ Random notes
  - Generally avoid assigning values to variables at declaration time,
    especially so for complex and/or run-time dependent values.
 
  - Generally avoid assigning values to variables at declaration time,
    especially so for complex and/or run-time dependent values.
 

- - Consistently use g_try_malloc() / g_try_malloc0(). Do not use standard
+ - Consistently use g_*malloc() / g_*malloc0(). Do not use standard

    malloc()/calloc() if it can be avoided (sometimes other libs such
    as libftdi can return malloc()'d memory, for example).
 
  - Always properly match allocations with the proper *free() functions. If
    malloc()/calloc() if it can be avoided (sometimes other libs such
    as libftdi can return malloc()'d memory, for example).
 
  - Always properly match allocations with the proper *free() functions. If

-   glib's g_try_malloc()/g_try_malloc0() was used, use g_free() to free the
+   glib's g_*malloc()/g_*malloc0() was used, use g_free() to free the

    memory. Otherwise use standard free(). Never use the wrong function!
 
    memory. Otherwise use standard free(). Never use the wrong function!
 

- - Never use g_malloc() or g_malloc0(). These functions do not return NULL
-   if not enough memory is available but rather lead to an exit() or segfault
-   instead. This behaviour is not acceptable for libraries.
-   Use g_try_malloc()/g_try_malloc0() instead and check the return value.
+ - We assume that "small" memory allocations (< 1MB) will always succeed.
+   Thus, it's fine to use g_malloc() or g_malloc0() for allocations of
+   simple/small structs and such (instead of using g_try_malloc()), and
+   there's no need to check the return value.
+
+   Do use g_try_malloc() or g_try_malloc0() for large (>= 1MB) allocations
+   and check the return value.

 
  - You should never print any messages (neither to stdout nor stderr nor
    elsewhere) "manually" via e.g. printf() or g_log() or similar functions.
 
  - You should never print any messages (neither to stdout nor stderr nor
    elsewhere) "manually" via e.g. printf() or g_log() or similar functions.


@@ -105,7 +103,7 @@ Random notes
  - Consistently use the same naming convention for #include guards in headers:
    <PROJECTNAME>_<PATH_TO_FILE>_<FILE>
    This ensures that all #include guards are always unique and consistent.
  - Consistently use the same naming convention for #include guards in headers:
    <PROJECTNAME>_<PATH_TO_FILE>_<FILE>
    This ensures that all #include guards are always unique and consistent.

-   Examples: LIBSIGROK_LIBSIGROK_H, LIBSIGROK_HARDWARE_MIC_985XX_PROTOCOL_H
+   Example: LIBSIGROK_HARDWARE_MIC_985XX_PROTOCOL_H

 
  - Consistently use the same naming convention for API functions:
    <libprefix>_<groupname>_<action>().
 
  - Consistently use the same naming convention for API functions:
    <libprefix>_<groupname>_<action>().