Building Ioto from Source
Ioto releases are available as source code distributions from the Builder Site. To download, first create an account and login, then define your product and select Ioto as the device agent.
Finally, click the download link from the product list and select the Ioto source code package.
The Ioto source distribution contains all the required source files, headers, and build tools for Ioto. The software supports two platforms for building from source.
- Make
- Xcode or Visual Studio Code
You can build by typing make or you can select one of the IDE projects under the projects directory.
Several build environments are supported:
- Linux — Linux 4 with GNU C/C++
- Mac OS X — Mac OS X 11 or later
For other environments, you will need to cross-compile. The source code has been designed to run on FreeBSD, Linux, Mac OS X, VxWorks, FreeRTOS and other operating systems. It has been tested under Fedora and Ubuntu Linux based on the Linux 4 Kernel, and MAC OS X 11.
Preparing to Build
To build from source, the NodeJS and NPM build tools must first be installed.
To install Node with NPM:
1 | |
and download the LTS distribution. Follow the instructions to install.
Building with Make
Ioto provides a suite of generated, pre-configured Makefiles for common platforms. These are simple, clean, generated makefiles that build a default configuration for a specific operating system. These makefiles are provided under the ./projects directory.
A top level Makefile is also provided that parses your ioto.json5 configuration file, detects your operating system and CPU architecture and then invokes the appropriate project Makefile for your system. To run:
Installing with Make
You can install the newly built software via:
You can remove by:
If you need to deploy to a different system or capture the build artifacts, you can install to a specific directory via:
Build Profiles
You can change the build and execution profile by editing ioto.json5. Two build profiles are supported:
- dev
- prod
The dev profile will build Ioto with debug symbols and local state directories suitable for debugging.
The prod profile will build Ioto optimized without debug symbols. Database state and logs will be stored in the appropriate O/S locations.
Configuration
You do not need to use a configure program when building via make. Instead, you edit the ioto.json5 configuration options and then run make to generate a src/ioto-config.h configuration file that will conditionally compile the required services.
If you change the ioto.json5 settings, you may need to rebuild to reflect the changed configuration. To rebuild:
1 2 | |
The ioto.json5 services property collection defines which services to build and enable when running Ioto.
The ioto.json5 configuration file has some conditional properties that are applied depending on the selected mode and profile. These properties are nested under the conditional property and the relevant set are selected are copied to overwrite properties of the same name at the top level. This allows a single configuration file to apply different settings based on the current values of the mode and profile properties.
Operational Modes
You can select an operational mode that will customize the services and capabilities provided by Ioto.
The mode is determined by the ioto.json5 "mode" property. You can modify this by editing the ioto.json5 file.
The following modes are supplied, and you can easily add your own mode to the ioto.json5 file.
- cloud
- local
To display the current mode, invoke:
1 | |
Cross Compiling with Make
Building Ioto for platform different to that of the local system is called cross compiling. Sometimes this compiling is just for a different instruction set (say x64 instead of x86). Other times, it is for a completely different operating system and/or CPU architecture. In such cases, a cross-compiler is typically required to build for the target platform.
To cross compile, you will typically need to install a cross-compiler tool chain for your target architecture. Once installed and before you attempt to build Ioto, it is best to test compiling a simple, stand-alone HelloWorld program to ensure the cross compiler is working correctly.
To cross-compile Ioto, you invoke the relevant project makefile and pass the required CPU architecture as a make variable. For example, to cross compile for VxWorks on ARM:
When make executes, it places the output products (executables, libraries and objects) in a platform-specific output directory. This is named using the form: OS-ARCH-PROFILE. For example: vxworks-arm-debug. In this manner, make can be invoked multiple times, once for each target platform and the results will be captured in separate platform output directories. Some of the supported architectures for the ARCH field are:
1 | |
The PROFILE variable is a descriptive name chosen by you for your configuration.
If there is not a makefile for your target operating system, copy the closest makefile and edit to suit your target platform.
Specifying the CPU
The build will use the generic CPU type within the specified architecture. To override the default choice and specify a CPU type within an architecture, use the CPU variable. For example:
Specifying a Tool Chain
You may need to specify where make can locate your cross-compiler and other tools. You can supply these via the make variables: CC, CFLAGS, DFLAGS, IFLAGS, LD and LDFLAGS. For example:
Building with an IDE
Ioto includes Visual Studio and Xcode projects that provide easy access for building and debugging. The generated IDE projects will build Ioto using default settings and are somewhat limited in their configurability.
Building with Xcode
To build with the Xcode on Mac OS X, run Xcode 12 or later and open the projects/ioto-macosx.xcodeproj project. Then select the Product -> Build menu option to build the software. To debug, you will need to create use Product -> Edit Scheme to set the executable to run under the Info tab, and define the working directory under the Options tab.
Building with OpenSSL
Ioto includes support for multiple TLS stacks including:
MbedTLS is a compact TLS implementation suitable for embedded devices. Ioto includes the MbedTLS distribution and will build with it by default. OpenSSL is a leading open source TLS stack that is faster, but bigger.
Downloading OpenSSL
Most Linux distributions include OpenSSL with their default distribution. We support the latest stable and LTS releases only. Once OpenSSL is built, you will need to supply the Ioto project with the pathname to your OpenSSL source code directory.
Building with OpenSSL via Make
If you are building with make, first copy the built OpenSSL libraries to your build/*/bin directory. Then set the path to your OpenSSL source directory when you run make:
Building Ioto with OpenSSL via Visual Studio
To set the path to your OpenSSL source directory, select "View -> Property Manager". Select "ioto" and edit the "product" property page by expanding Debug. In the "product Property Pages" dialog, add a User Macro definition for the OpenSSL source directory.
Building Ioto with OpenSSL via Xcode
To set the path to your OpenSSL source directory, click on "ioto-macosx-default" on the left to display the project settings. Select under "PROJECT" the "ioto-macosx-openssl_10" project and click on "Build Settings" in the panel in the center. Scroll down to define the path to your OpenSSL source code directory in the ME_COM_OPENSSL_PATH property.
GitHub Issues
A GitHub repository is used to track issues and for discussions.
Go to the GitHub Issues to track bugs, security issues or participate in general discussions regarding Ioto.