HACKING

   1 If you want to hack on gphoto2 (or a camera driver for gphoto2),
   2 please follow some rules to make our work easier:
   3
   4
   5 licensing
   6 ---------
   7
   8 We urge you to license your contributions under the LGPL so we can
   9 distribute gphoto2 under the LGPL as well.
  10
  11
  12 patches
  13 -------
  14
  15 ... are always welcome.
  16
  17 We prefer patches against the current SVN trunk very much over
  18 patches against old released versions, but these are also welcome :-)
  19
  20 source files
  21 ------------
  22
  23 Every source file (file_name.c) should have the following layout:
  24
  25 /* Licence, author, etc. */
  26 #include "config.h"
  27 #include "file_name.h"
  28
  29 #include <std*.h> (i.e. stdlib, stdio, string, etc.)
  30
  31 #include <gphoto2/gphoto2-*.h> (what you need)
  32
  33 /* Source code here. */
  34
  35 header files
  36 ------------
  37
  38 Please use the following layout:
  39
  40 /* Licence, author, etc. */
  41 #ifndef __FILE_NAME_H__
  42 #define __FILE_NAME_H__
  43
  44 #include <whatever is needed for the _header_>
  45
  46 /* Declarations */
  47
  48 #endif /* __FILE_NAME_H__ */
  49
  50 camlib
  51 ------
  52
  53 Camera libraries are often very sensitive to changes. Therefore,
  54 before you commit any changes, double check with the author that your
  55 changes won't break the driver.
  56
  57 If you want to write a driver for gphoto2, the easiest way to do so
  58 would be to copy over the contents of camlibs/template and fill in
  59 your code.
  60
  61 Use something like CHECK_RESULT (see for example
  62 libgphoto2/filesys.c).
  63
  64 Let's say you write a driver called sillycam. Please set up a file
  65 called library.c containing all gphoto2-specific code (like
  66 camera_init) and another two files called sillycam.c and sillycam.h
  67 containing the "magic", that is all gp_port_[read,write] functions and
  68 the basic logic of the communication. This makes it easier for us to
  69 adapt your code if anything should change in the gphoto2-API.
  70
  71 Use the port provided by camera->port.
  72
  73 Use the filesystem provided by camera->fs and set up the callbacks so
  74 that libgphoto2 can cache listings and file-information.
  75
  76 Please keep track of the changes to the sillycam camlib in the file
  77
  78    camlib/sillycam/ChangeLog
  79
  80 For test compiling and installing only the sillycam and doofuscam
  81 camlibs, you can use
  82
  83    make -C camlibs sillycam.la doofuscam.la
  84
  85 and
  86
  87    make DRIVERS="sillycam.la doofuscam.la" install-drivers
  88
  89 respectively.
  90
  91 Compiling all camlibs is sped up considerably on N CPU core
  92 computers using "make -jN".
  93
  94
  95
  96
  97 libgphoto2
  98 ----------
  99
 100 If you add code, use the coding style of that file. This is, code like
 101
 102 int
 103 my_func (int arg)
 104 {
 105         int var, res;
 106
 107         /*
 108          * This is a multiline
 109          * comment. Use TAB for
 110          * indentation!
 111          */
 112         res = gp_some_action (var);
 113
 114         /* This is a simple one-line comment */
 115         if (res < 0) {
 116                 gp_log (GP_LOG_DEBUG, "Error happened!");
 117
 118                 /* Note that we _don't_ indent the case statements */
 119                 switch (res) {
 120                 case GP_ERROR:
 121                         gp_log (GP_LOG_DEBUG, "Generic error");
 122                         break;
 123                 default:
 124                         gp_log (GP_LOG_DEBUG, "Not a generic error");
 125                 }
 126                 return (res);
 127         }
 128
 129         return (GP_OK);
 130 }
 131
 132 Please always check the return value of gp_-functions! We defined some
 133 handy macros all over the place (like CHECK_RESULT) - by using those,
 134 you'll avoid lots of if {} else {}.
 135
 136 Emacs users may define and use a gphoto-c-mode by putting the
 137 following stuff into their .emacs file:
 138
 139 -----8<------------------------------------------------
 140
 141 ;;* gphoto-c-mode
 142 ;;*=====================================================================
 143 (defun gphoto-c-mode ()
 144   "C mode with adjusted defaults for gphoto hacking"
 145   (interactive)
 146   (c-mode)
 147   (c-set-style "linux")
 148   (setq indent-tabs-mode t)
 149   (font-lock-mode))
 150
 151 ;;
 152 (setq auto-mode-alist (cons '("/home/user/src/gphoto.*\\.[ch]$" . gphoto-c-mode)
 153                             auto-mode-alist))
 154
 155 -----8<------------------------------------------------
 156
 157 compatibility
 158 -------------
 159
 160 One gphoto2 has been officially launched as a 2.0 version, it is important
 161 that the API does not change frequently.  It is annoying to users when they
 162 have to upgrade all sort of libraries and applications just to get an
 163 upgraded camera driver.  Once the 2.0 release has been made, try to
 164 follow these guidelines:
 165
 166     - New versions of the gphoto2 core libraries in the 2.0 series shall
 167     work with all older 2.0 camera libraries
 168
 169     - New versions of the gphoto2 camera libraries in the 2.0 series shall
 170     work with all older 2.0 core libraries (this one may be relaxed)
 171
 172     - Before fixing 2.0 in stone, look for weaknesses in the current
 173     APIs that may preclude enhancements in the future.  For instance, there
 174     should be some filler entries added to the end of struct _CameraFunctions
 175     so that a newer camera library that tries to fill in an entry that
 176     is added in gphoto2 ver. 2.1 that doesn't exist there now won't
 177     overwrite something important.
 178
 179     - Try to work using the existing API instead of making minor
 180     changes here and there; think about whether the change you're proposing
 181     will demonstratively benefit gphoto2 or it's just a "nice to have"
 182
 183     - Instead of adding a new parameter to a function, create a new function
 184     that enhances the other one (where appropriate)
 185
 186     - If a new parameter is absolutely needed in an existing function
 187     call, rename the function with the new parameter, but leave the
 188     existing function as is, calling the new function with a default value
 189     for the new parameter
 190
 191     - When adding entries to a common structure, add them to the end of the
 192     struct so that the other members aren't shifted around.  Consider what
 193     will happen if that member is not filled in by an older application.
 194
 195     - Don't delete entries from a common struct; instead, just rename them
 196     into filler entries.
 197
 198     - If there is a very good reason to break compatibility, wait until
 199     release 3.0 to make those changes
 200
 201     - Delay the release of 3.0 until the benefits outweigh the consequences
 202     to the user of an incompatible library version.
 203
 204
 205 portability
 206 -----------
 207
 208 Please remember that people will be running gphoto2 on a wide variety
 209 of operating systems and CPUs and will be compiling it on a wide
 210 variety of C compilers.  As you write your code, be sure not to make
 211 any assumptions in your code that aren't in the ANSI C89 standard.
 212 If your code absolutely needs some feature or header file that isn't
 213 available everywhere, write an autoconf test so that the configure
 214 script will detect if that feature is available at compile time and
 215 provide an alternative for those compilers that don't support it.
 216
 217 There are lots of subtle portability issues that you should keep in
 218 the back of your mind.  Following are some of the major ones that affect
 219 gphoto2.  See the paper "Notes on Writing Portable Programs in C" at
 220 <URL:http://www.literateprogramming.com/portableC.pdf> or "Writing
 221 Portable C with GNU Autotools" at
 222 <URL:http://sources.redhat.com/autobook/autobook/autobook_110.html#SEC110>
 223 for more details.
 224
 225
 226 * A char can be signed or unsigned.
 227
 228 Use 'signed char' or 'unsigned char', or int8_t or uint8_t from _stdint.h,
 229 to be sure to get the type you want when it is important.
 230
 231
 232 * A pointer is not necessarily an int.
 233
 234 Don't cast a pointer to an int and vice-versa.
 235
 236
 237 * An int can be almost any width.
 238
 239 Don't assume that it's 32 or 16 bits or any other value.  Instead,
 240 if you need a variable of a certain size, include the gphoto2 header
 241 file _stdint.h (or gphoto2-endian.h) and use the C99-style fixed-width
 242 types declared therein.  If you don't really care about the size of a
 243 variable (e.g. as the index variable in a small for loop), you can still
 244 use an int as it's often the most efficient type for each processor.
 245 It's usually the case that a char is 8 bits, int is at least 16 bits,
 246 and a long is at least 32 bits.  Never assume that int or long (or char,
 247 for that matter) have a specific size, or that they will overflow at a
 248 particular point.  Use a size-specific type (e.g. uint32_t) if necessary.
 249
 250
 251 * The sequence of bytes received from a camera isn't necessarily the
 252 same as how those bytes are stored in a C struct in memory.
 253
 254 Many compilers will place padding bytes between the elements of a C
 255 struct to improve run-time efficiency on the target processor.  This
 256 means that if you read a camera packet directly into such a struct,
 257 the bytes will not line up and your program will use the wrong values.
 258
 259 A similar problem occurs even if you read just a couple of bytes
 260 into an int, if gphoto is running on a processor with a different
 261 "endianness" than the camera.
 262
 263 The most portable solution is to use the macros available in the
 264 gphoto2-endian.h header file.  When you read a packet from a camera
 265 (writing is similar), use a uint8_t array or heap space to store the
 266 raw packet.  Extract each member of the packet out of the array one at a
 267 time using a macro like be32atoh from gphoto2-endian.h.  Those macros
 268 take care of both those problems at once.
 269
 270 The macros have the form AANN[a]toh or htoAANN[a], where AA is `le'
 271 (little-endian) or `be' (big-endian), NN is 16 or 32 (bits in the
 272 word) and `a', if present, means that the preceding type is located in
 273 a byte array, not an integer. `h' refers to `host', and could be big
 274 or little-endian depending on the current CPU.  Upper-case versions of
 275 these macros (where appropriate) do the conversion in place.  Do a
 276 'man ntohl' to find out more about why these are needed, and the generated
 277 gphoto2-endian.h file for more descriptions.
 278
 279
 280 * Your code won't necessarily be compiled with gcc.
 281
 282 gcc is a great C compiler, but it isn't installed on everybody's
 283 systems (yet!).  Avoid use of proprietary gcc language extensions and
 284 features that aren't available in ANSI C89 compilers.  Sure, there's
 285 probably some code that would be more elegant using a gcc language
 286 extension, but somebody, somewhere will be denied the use of the best
 287 digital camera application in existence because of it.
 288
 289 This also applies to new standard C features that appeared in the
 290 C99 specification of the language.  There is not much support yet
 291 in the installed base of C compilers to allow unrestricted use, but
 292 this will change as time goes by.  In the meantime, use autoconf to
 293 detect if the feature is available at run-time and act appropriately
 294 (for an extreme example, see how configure handles the C99 header
 295 file <stdint.h> or inline keyword).
 296
 297 Although one-line comments starting with // have been available
 298 in most compilers for several years, they were only officially
 299 added to the ANSI C99 spec and some compilers out there still
 300 don't support them.  The "inline" keyword also falls into the same
 301 category, but configure tests for this feature at compile time
 302 and supplies the appropriate inline keyword as a macro.  Finally,
 303 don't add compiler-specific flags to make files directly, as many
 304 of them are specific to one compiler and will cause the build to
 305 fail when using another.
 306
 307
 308 Local Variables:
 309 mode:text
 310 End: