Developing application

Development environment for Application Developers

Developers use the system development kit for developing applications. This includes the following:

Item	Contents
VOS3 build tools	gcc compiler gcc build tools
VOS3 host debug tools	gdb debugger
VOS3 device debug tools	debug tools download package (dropbear, gdb, gdbserver, strace, etc.)
VOS3 packaging and development signing tool	packman
VOS3 system download files	VOS3 system download files for system update
VOS3 / ADK APIs	ADK headers, link libraries
ADK Documentation	ADK release notes ADK component programmers guides examples

ADK API Libraries

Applications use API prototypes from provided header files and link against the ADK libraries to access these APIs.

Component	Client Libraries	Client Header Files
ADK GUIPRT	libvfiguiprt.so	html/gui.h html/prt.h
ADK IPC	libvfiipc.so libvfiipctls.so	ipc/ipc.h ipc/notify.h ipc/jsobject.h ipc/tls.h
ADK COM	libcom.so	com/libcom.h com/libcom3.h
ADK CCP	libccp.so	com/libccp.h
ADK MAC	libvfimac.so libvficpr.so	sysinfo/mac.h
ADK PM	libvfisyspm.so	sysinfo/vfisyspm.h
ADK EMV	libEMV_CTLS_Client.a libEMV_CT_Client.a libEMV_CT_Link.so libEMV_CTLS_Link.so libsdiclient.a libTLV_Util.so	emv/EMV_Common_Interface.h emv/EMV_CT_Interface.h emv/EMV_CTLS_Interface.h emv/EMV_CT_SerInterface.h emv/EMV_CTLS_SerInterface.h emv/E2E_EMV_CT_Serialize.h emv/E2E_EMV_CTLS_Serialize.h emv/btlv.h emv/EMV_CT_XML.h emv/EMV_CTLS_XML.h emv/hexutil.h
ADK MSR	libsdiclient.a	msr/msr.h
ADK TEC	libsdiclient.a	tec/tec.h
ADK NFC	libsdiclient.a	nfc/NFC_Client.h nfc/NFC_Interface.h
ADK SYS	libvfisysinfo.so libvfisysbar.so	sysinfo/sysinfo.h sysinfo/leds.h sysinfo/sysbar.h sysinfo/sysbeep.h sysinfo/inifile.h
ADK CPL	libcpl.so	commerce/commerce.h
ADK LOG	liblog.so	log/liblog2.h
ADK ISO8583	libiso8583.so	iso8583/ConstData.h iso8583/dl_err.h iso8583/dl_str.h iso8583/dl_iso8583.h iso8583/SafeBuffer.hpp iso8583/dl_iso8583_fields. iso8583/dl_base.h iso8583/dl_iso8583_common. iso8583/dl_mem.h iso8583/defs/dl_iso8583_de iso8583/defs/dl_AS2805_def iso8583/fwd/ConstData.h iso8583/fwd/SafeBuffer.hpp
ADK INF	libinf.so libinf_util.so	inf/infodb.h inf/inf_util.h
ADK SND	libsound.so	sound/sound.h
ADK SEC	libsec2.so	sec/libsec.h
ADK EVT	libevt.so	evt/libevt.h
ADK AGT	libsvc_tms.so	agt/svc_tms.h agt/tms_status.h
SDI CLIENT	libsdiclient.a libsdiprotocol.so	sdiclient/sdi_if.h sdiclient/sdiprotocol.h
SDI C++ API	libsdiapi.so	sdiapi/sdi.h
INSTALLER	libinstall.so	installer/installer.hpp

Open Source libraries

In addition to ADK APIs, applications can use the following provided Open Source libraries directly from within applications.

Component	libraries	header files	Notes
OpenSSL	libssl.so libcrypto.so	all headers
Compression	libz.so	all headers
CURL	libcurl.so	all headers
SQLite	libsqlite3.so	all headers
Libxml	libxml.so libxml2.so	all headers	added in OSS release 1.9.1

Secondary Library dependencies

Provided client libraries have additional dependencies that are usually not reflected to the applications and they are being resolved internally.

Applications should only link to the above libraries, unless told differently.

VOS3 Platform internal libraries

Do not use internal libraries

The SDK contains additional libraries not listed above as supported ADK or Open Source libraries.

These libraries do not expose public interfaces for applications and can be subject to change with new VOS3 releases.

Please do not use these libraries directly!

Building Applications

The VOS3 toolchain comes with all typical tools to cross-compile and link applications:

Toolchain Application	Description
arm-none-linux-gnueabihf-addr2line	Convert addresses or symbol+offset into file names and line numbers
arm-none-linux-gnueabihf-ar	Create, modify, and extract from archives
arm-none-linux-gnueabihf-as	The portable GNU assembler
arm-none-linux-gnueabihf-c++	GNU project C and C++ compiler
arm-none-linux-gnueabihf-c++filt	Demangle C++ and Java symbols
arm-none-linux-gnueabihf-cpp	The C Preprocessor
arm-none-linux-gnueabihf-dwp	The DWARF packaging utility
arm-none-linux-gnueabihf-elfedit	Update ELF header and program property of ELF files
arm-none-linux-gnueabihf-g++	GNU project C and C++ compiler
arm-none-linux-gnueabihf-gcc arm-none-linux-gnueabihf-gcc-11.2.1	GNU project C compiler
arm-none-linux-gnueabihf-gcc-ar	Create, modify, and extract from archives
arm-none-linux-gnueabihf-gcc-nm	List symbols from object files
arm-none-linux-gnueabihf-gcc-ranlib	Generate an index to an archive
arm-none-linux-gnueabihf-gcov	Coverage testing tool
arm-none-linux-gnueabihf-gcov-dump	Offline gcda and gcno profile dump tool
arm-none-linux-gnueabihf-gcov-tool	Offline gcda profile processing tool
arm-none-linux-gnueabihf-gdb	The GNU Debugger
arm-none-linux-gnueabihf-gdb-add-index	Add index files to speed up GDB
arm-none-linux-gnueabihf-gprof	Display call graph profile data
arm-none-linux-gnueabihf-ld arm-none-linux-gnueabihf-ld.bfd arm-none-linux-gnueabihf-ld.gold	The GNU linker
arm-none-linux-gnueabihf-lto-dump	Tool for dumping LTO object files
arm-none-linux-gnueabihf-nm	List symbols from object files
arm-none-linux-gnueabihf-objcopy	Copy and translate object files
arm-none-linux-gnueabihf-objdump	Display information from object files
arm-none-linux-gnueabihf-ranlib	Generate an index to an archive
arm-none-linux-gnueabihf-readelf	Display information about ELF files
arm-none-linux-gnueabihf-size	List section sizes and total size of binary files
arm-none-linux-gnueabihf-strings	Print the sequences of printable characters in files
arm-none-linux-gnueabihf-strip	Discard symbols and other data from object files

Compiler and Linker Settings

The following tables give an overview of recommended compiler and linker flags for application development on VOS3 platform.

CFLAGS

--sysroot $(SYSROOT_DIR)	Set the sysroot path to the root directory of your installed SDK
-D_VOS3	Flagging for platform-dependent code
-fstack-protector-strong	Enable extra checks for buffer overflows and and stack smashing
-fPIE	Enable position independent executable (**only use for executables**)
-fPIC	Enable position independent code (**only for shared/static libraries**)
-Wall	Enable all warnings (see manual of gcc for details)
-Wextra	Enable extra warnings (see manual of gcc for details)
-Wformat=2	Enable format check for functions like printf, scanf, ...
-Wformat-security	Enable warning about potentially malicious use of format functions
-Werror=format-security	Make format-security warnings an error
-Wtrampolines	Warn about trampolines generated for pointers to nested functions
-Werror=trampolines	Make trampoline warnings an error
-Wreturn-type	Warn about missing return types
-Werror=return-type	Make return type warnings an error
-Wno-psabi	Suppress GCC notes about ABI changes for parameter passing (informational only; not affected by -Wall/-Wextra)

LDFLAGS

--sysroot $(SYSROOT_DIR)	Set the sysroot path to the root directory of your installed SDK
-L$(SYSROOT_DIR)/usr/local/lib	Add this directory of your installed SDK to the linker search path
-fPIE -pie	Enable position independent executable (only use for executables)
-Wl,-rpath,'$$$$ORIGIN'	Set RPATH
-Wl,-z,relro,-z,now,-z,noexecstack	relro - Don't create an ELF "PT_GNU_RELRO" segment header in the object. now - Resolve all symbols on startup or dlopen noexecstac - Marks the object as requiring executable stack.

32 bits vs 64 bit user applications

Even if hardware and kernel supports 64 bits, application and ADK (executables and libraries) remain 32 bit. The goal is to keep compatibility between devices and also preserve size and performance.

This is enforced by packman.

Example: Hello World

The following part shows key parts of a sample project using ADK-GUI and SDI-API components. It's based on a Makefile project which shows compilation and generation of VOS3 load packages.

Full source package can be obtained from Verifone support.

Makefile

# Set path to toolchain
TOOLCHAIN_DIR:=/opt/vos3/bin
# Set path to SDK
SYSROOT_DIR:=$(HOME)/sdk/vos3/sdk-26
# Set path to packaging tool
PACKMAN:=packman
# Specify compilers and linker
CC:=$(TOOLCHAIN_DIR)/arm-none-linux-gnueabihf-gcc --sysroot $(SYSROOT_DIR)
CXX:=$(TOOLCHAIN_DIR)/arm-none-linux-gnueabihf-g++ --sysroot $(SYSROOT_DIR)
LD:=$(TOOLCHAIN_DIR)/arm-none-linux-gnueabihf-g++ --sysroot $(SYSROOT_DIR)
# Set CFLAGS
CFLAGS= -D_VOS3 -fstack-protector-strong -Wall -Wextra -Wformat=2 -Wformat-security -Werror=format-security -Wtrampolines -Werror=trampolines -Wno-psabi
CFLAGS_DEBUG= $(CFLAGS) -g -ggdb
# Set additional CXXFLAGS
CXXFLAGS= -std=c++14
CXXFLAGS_DEBUG= $(CXXFLAGS) -g -ggdb
# Set linker flags
LDFLAGS= -Wl,-rpath,'$$$$ORIGIN' -Wl,-z,relro,-z,now,-z,noexecstack
# Specify link libraries
LIBS= -lvfiguiprt -lsdiapi -lvfiipc
# Set project sources
SOURCE_RELEASE=main.cpp
SOURCE_DEBUG=$(SOURCE_RELEASE)
# Fetch object files for dependencies - No need to edit
OBJ:=$(patsubst %,obj/1/%,$(subst ..,_,$(patsubst %.cpp,%.o,$(patsubst %.cxx,%.o,$(SOURCE_RELEASE:.c=.o)))))
OBJ2:=$(patsubst %,obj/2/%,$(subst ..,_,$(patsubst %.cpp,%.o,$(patsubst %.cxx,%.o,$(SOURCE_DEBUG:.c=.o)))))
DEP:=$(OBJ:%.o=%.d) $(OBJ2:%.o=%.d)
OBJDIR:=obj/1 obj/2
# release build target
vos3demo: $(OBJ)
$(LD) $(LDFLAGS) -o $@ $^ $(LIBS)
# debug build target
vos3demo-debug: CFLAGS:=$(CFLAGS_DEBUG)
vos3demo-debug: CXXFLAGS:=$(CXXFLAGS_DEBUG)
vos3demo-debug: $(OBJ2)
$(LD) $(LDFLAGS) -o $@ $^ $(LIBS)
# full distribution build
dist: dist-debug dist-release dist-remove
# release distribution build
dist-release: dist/dl.vos3_demo.tar
dist/dl.vos3_demo.tar: vos3demo
mkdir -p dist dist_tmp_rel/vos3demo/demo/
cp manifest.json dist_tmp_rel/vos3demo/
cp -r www dist_tmp_rel/vos3demo/demo/
cp vos3demo dist_tmp_rel/vos3demo/demo/
(cd dist_tmp_rel; $(PACKMAN) build -t vos3 -s dev -i vos3demo -f -d ../dist/dl.vos3_demo.tar)
rm -Rf dist_tmp_rel
# debug distribution build
dist-debug: dist/dl.vos3_demo-debug.tar
dist/dl.vos3_demo-debug.tar: vos3demo-debug
mkdir -p dist dist_tmp_dbg/vos3demo/demo/
cp manifest.json dist_tmp_dbg/vos3demo/
cp -r www dist_tmp_dbg/vos3demo/demo/
cp vos3demo-debug dist_tmp_dbg/vos3demo/demo/vos3demo
(cd dist_tmp_dbg; $(PACKMAN) build -t vos3 -s dev -i vos3demo -f -d ../dist/dl.vos3_demo-debug.tar)
rm -Rf dist_tmp_dbg
# remove package distribution build
dist-remove: dist/dl.vos3_demo-remove.tar
dist/dl.vos3_demo-remove.tar:
mkdir -p dist dist_tmp_rem
cp manifest-rem.json dist_tmp_rem/manifest.json
(cd dist_tmp_rem; $(PACKMAN) build -s dev -t vos3 -i . -f -d ../dist/dl.vos3_demo-remove.tar)
rm -Rf dist_tmp_rem
# clean target
clean:
rm -rf obj compile_commands.json vos3demo vos3demo-debug
# distribution clean target
dist-clean: clean
rm -rf dist
# phony targets
.PHONY: clean dist-clean dist-remove dist-debug dist-release dist
################################################################################
# HELPERS - No need to edit
################################################################################
define add_rule =
$(1)/%.o: %.c
@mkdir -p $$(@D)
$$(CC) $$(CFLAGS) -c -o $$@ $$< -MT $$@ -MMD -MP -MF $(1)/$$*.d
$(1)/%.o: %.cpp
@mkdir -p $$(@D)
$$(CXX) $$(CFLAGS) $$(CXXFLAGS) -c -o $$@ $$< -MT $$@ -MMD -MP -MF $(1)/$$*.d
$(1)/%.o: %.cxx
@mkdir -p $$(@D)
$$(CXX) $$(CFLAGS) $$(CXXFLAGS) -c -o $$@ $$< -MT $$@ -MMD -MP -MF $(1)/$$*.d
$(1)/_/%.o: ../%.c
@mkdir -p $$(@D)
$$(CC) $$(CFLAGS) -c -o $$@ $$< -MT $$@ -MMD -MP -MF $(1)/_/$$*.d
$(1)/_/%.o: ../%.cpp
@mkdir -p $$(@D)
$$(CXX) $$(CFLAGS) $$(CXXFLAGS) -c -o $$@ $$< -MT $$@ -MMD -MP -MF $(1)/_/$$*.d
$(1)/_/%.o: ../%.cxx
@mkdir -p $$(@D)
$$(CXX) $$(CFLAGS) $$(CXXFLAGS) -c -o $$@ $$< -MT $$@ -MMD -MP -MF $(1)/_/$$*.d
endef
$(foreach p,$(OBJDIR),$(eval $(call add_rule,$(p))))
-include $(DEP)

main.cpp

#include <html/gui.h>
#include <html/jsobject.h>
#include <sdiapi/sdi.h>

int main(int argc, char **argv) {
    (void) argc; (void) argv;
    vfigui::stringmap values;
    values.insert(std::make_pair("header_title", "Hello VOS3 World"));
    vfisdi::SDIClient client;
    client.setProtocol(vfisdi::SDIClient::PROTOCOL_C);
    if(vfisdi::OK != client.connect("127.0.0.1")) {
        return 1;
    }
    
    int ret = -1;
    while(ret != 0) {
        switch(ret) {
            case 1: {// Get SDI Info
                std::vector<vfisdi::SDIClient::ComponentVersion> info;
                client.sysGetSDIVersion(info);
                std::string sn;
                client.sysGetSerialNumber(sn);
                std::string vv;
                client.sysGetPropertyString(vfisdi::SYS_PROP_VAULT_VERSION, vv);
                std::string os;
                client.sysGetPropertyString(vfisdi::SYS_PROP_OS_VERSION, os);
                vfihtml::JSObject obj;
                for(size_t i = 0; i < info.size(); i++)
                    obj[i] = info[i].name + " - " + info[i].version;
                obj[obj.size()] = "VOS3: " + os;
                obj[obj.size()] = "K81: " + vv;
                obj[obj.size()] = "S/N: " + sn;
                values.insert(std::make_pair("infos", obj.dump()));
                break;
            }
            default:
                break;
        }
        ret = vfigui::uiInvokeURL(values, "index.html");
        values.erase("infos");
    }
    client.close();
    return 0;
}