For documentation purposes, “platform” is defined in terms of:
Platform dependencies such as operating systems or toolchains should be “released” versions (not beta) at least 1 month prior to the expected IoTivity release. Unless platform support is dropped, the expectation is that support would continue to move forward as the platform evolves (for instance, as new OS versions are released).
A fully-supported platform:
A fully supported platform is one where all non-experimental features work, and you cannot commit a feature that is enabled by default unless it works with all fully supported platforms. You can commit a new feature that is enabled by default if it works with all such platforms, but it need not work with preview/deprecated platforms.
There may be additional platforms that are not fully supported, due to lacking one or more of the above criteria. Other platforms or variations may be included in the code base and still build and run, but are not verified. For example, older compiler versions or newer versions of the OS may work fine. Bug fixes and feature porting may be on a best-effort basis from committers or contributors.
A core feature is supported on all fully-supported platforms, where (at the time of an IoTivity release) it:
An optional feature has the same criteria as a Core Feature, with the following exceptions:
There may be additional features that are not core or optional features, due to lacking one or more of the above criteria (e.g., not being available on all fully supported platforms). Experimental features shall not be enabled by default. They may or may not be compiled in by default.
API breaking changes can be made to experimental features.
Any platform-specific functions should be in files under the Platform Abstraction Layer (PAL) subtree (currently resource\c_common\platformname\).
New code should not duplicate functionality of a POSIX-compliant function that is available. If a given posix compliant function is not available on a given platform, then there are two choices:
The general principle is to not duplicate code and functionality in IoTivity when it exists natively on a given platform.
The path separator differs across platforms ('/' vs '\'). There has been some confusion about when to use
SConscript files. In short:
os.path.joinwhen constructing paths interpreted by Python itself, these will then be correct for the system it is running on. Especially necessary if Python is being asked to check for existence of a resource before doing something (
os.path.joinas SCons understands its own context and will do the right thing. An example is adding to
CPPPATH, which is always interpreted in the context of the directory of the
SConscriptdoing the work (unless an explicit change directory has taken place). It is fine to use POSIX-style paths here.
os.path.join. An example of this case is
resource/csdk/security/unittest/SConscript, which builds a path to be passed to the compiler inside a define (
Early iterations of the build scripts used copies of paths saved in the construction environment (
BUILD_DIR) to help build paths to things. This is not wrong, but led to a number of places where building was accidentally done in the source directory instead of the variant directory, which in turn causes problems for concurrent builds with different parameters. The normal approach should be to use a relative path first, if that gets to looking compilacted, a topdir-relative path (starts with
#) can be used. Both will be adjusted for the variant directory in effect. If you REALLY need to have the source directory, like for certain checks to be done by Python code, it can be obtained this way:
.abspath, but avoid using abspath unless it is absolutely needed).
Often there are things that do not apply to all target OS's and so an SConscript file needs to put some functionality under an 'if' test against target_os. The following applies when deciding when to use an inclusion test (i.e., “==” or “in”) vs an exclusion list (i.e., “!=” or “not in”):
#ifdefs in code outside the PAL subtree should not be platform checks, but may be feature checks (e.g., #ifdef HAVE_SNPRINTF). In most cases, however, ifdefs that vary by platform should be placed within the PAL subtree rather than in other code.
Sometimes there are ifdefs in Test code due to platform-specific issues. Ideally any #ifdef's in Test code should also be feature checks. If this is not practical, then the same rule for target_os in SConscript files applies to ifdef checks for platform-specific defines: