VRPN 07.22

Coding Rules

If you are writing code that is part of the vrpn library, these are the rules to play by. All of these are solutions to problems we have run into at some point. Following these will keep us from repeating some of the previous mistakes, and save us time in the long run.

To play nicely with other libraries, all callback functions must be declared to use VRPN_CALLBACK linkage convention. For example:
```
typedef void (VRPN_CALLBACK *vrpn_ANALOGCHANGEHANDLER) (void * userdata,
           const vrpn_ANALOGCB info);
```
To enable the DLL to work correctly, all files in the VRPN library must also be included in the VRPNDLL project. All classes, functions, and 'extern' variables in these files must use the VRPN_API calling convention. VRPN_API is defined based on whether the code is being compiled to be part of the DLL, to be used from a DLL, or for static linkage based on compile-time definitions in the configuration files (vrpn_Configuration.h and the project files in Visual Studio).
Sections of the library that only work on a certain architecture must be guarded with #ifdef...#endif in the code, so that the library can compile on all the supported architectures.
Use the following architecture independent type instead of the native types for values that are going to be sent across the network. Otherwise, messages won't make it across the network between machines of differing native type sizes. These are defined in vrpn_Types.h:
- vrpn_uint8
- vrpn_int16
- vrpn_uint16
- vrpn_int32
- vrpn_uint32
- vrpn_float32
- vrpn_float64
- vrpn_true (these are of type vrpn_bool)
- vrpn_false
All constants, types, functions, classes and variables that are visible outside the library should be prefixed with vrpn_ or VRPN_, to avoid name collision with other libraries and applications. All other functions and variables must be declared static, and not mentioned in the #include files.
Message names beginning with "vrpn" are reserved for use in the library.
While working on Windows NT :
- Remove ^M characters from the end of lines in source code before checking the code in. Otherwise, it's hard to read in UNIX land. There are several ways of doing this, including to_unix on IRIX, dos2unix on Solaris, or the PC versions of CVS (which do it automatically upon checking in)
- For MS Visual C++ :
  - .dsp and .dsw should work on VC 6.0.
  - .dsp and .dsw files should assume that any needed 3rd party libraries are installed in the default file locations. Document what 3rd party libraries (and what versions) are needed in the README.txt file.
  - Projects which require files or libraries from other CVS modules should document which other modules are needed in the README.txt file. Don't duplicate the other modules in your module!
  - The project settings should be set so that anyone can build after checking the code out, without having to make changes. If there are optional flags or defines, they should be set for the most common case. We should make it as easy as possible for those who just want to install the application.

Last updated September 10, 2004