README.md

Maintenance

To build against a new upstream version:

0. Modify the "version" field in package.json, setting it to the version of iotivity against which you're building

1. Modify the references to the version in README.md

2. Build and optionally install the new version of iotivity

3. If you haven't installed iotivity in the previous step, you must now export environment variables OCTBSTACK_CFLAGS and OCTBSTACK_LIBS, because the next step needs them.

4. Run ./update-enums-and-constants.sh

5. Update the commitid in build-csdk.sh

6. If the CFLAGS and/or LIBS have changed, modify install.sh and/or octbstack.pc.in and make the same modifications in binding.gyp

7. Test the build with both built-in iotivity and with iotivity via pkgconfig:

   nvm use 0.12 && git clean -x -d -f -f && npm run-script ci && \
   nvm use 0.10 && git clean -x -d -f -f && npm run-script ci && \
   nvm use 0.12 && git clean -x -d -f -f && ./dist.sh --testonly && \
   nvm use 0.10 && git clean -x -d -f -f && ./dist.sh --testonly

   The build may fail in src/constants.cc or src/enums.cc, complaining about undefined constants. That's because update-constants-and-enums.sh is unaware of C precompiler definitions and so it may harvest constants which are not actually defined under the set of precompiler flags used for building. Thus, you may need to edit src/constants.cc and src/enums.cc by hand after having run update-constants-and-enums.sh.

The script ./update-constants-and-enums.sh reads the C SDK header files and generates the contents of src/constants.cc and src/enums.cc. Read the comments in the script before you modify either src/constants.cc or src/enums.cc.

Coding Style And Principles

Please follow the [jQuery][] coding style for the JavaScript files. You can format all JS and C++ files with the following command:

grunt format

When writing the bindings, data arriving from Javascript is considered unreliable and must be validated. If it does not validate correctly, an exception must be thrown immediately after the failed check, and the process must be aborted. Data arriving from C is considered reliable and can be assigned to Javascript immediately.

Functions converting Javascript structures to C structures are named c_CStructureName and have the following signature:

bool c_CStructureName( Local<Object> jsStructureName, CStructureName **p_putStructurePointerHere );

This signature allows us to throw an exception and return false if any part of jsStructureName fails validation. The caller can then also return false immediately, and the binding can ultimately return undefined immediately.

As a general principle, if a Javascript value fails validation, throw an exception immediately. Do not return false and expect the caller to throw the exception. Call it exception-at-the-point-of-failure.

Pointers to structures received from the C API may always be null. The functions converting those pointers to Javascript objects (js_CStructureName()) assume that they are not null. So, wrap the call to such a function in a null-check.

When filling out a C structure in a function c_CStructureName, create a local structure first, and only if all validations pass, memcpy() the local structure into the structure passed in.