Client Guide

NavDB Clients on GitHub provides the source for various client language libraries and utilities that can connect to a NavDB database.

Supported platforms (x86-64 only):

  • Linux

  • Mac OS X

  • Windows 10

 

Language-specific client libraries:

C, C++, Java, Python and PHP 7

 

Client utilities:

  • Command-line REPL client.

 

Connect-string

The connect string specifies connection settings and can be specified in:

  • The NAVDB_CONNECT_STRING environment variable.

  • A parameter passed to a client program.

 

An example of setting NAVDB_CONNECT_STRING in Linux/Mac:

export NAVDB_CONNECT_STRING=host=localhost,port=3334,database=test,user=admin,password=testing

 

An example for Windows (or set in the Environment Variables settings under Control Panel).

export NAVDB_CONNECT_STRING=host=127.0.0.1,port=3334,database=test,user=admin,password=testing

 

Settings:

  • host: the hostname or IP address of the server.

  • port: the port that the NavDB server is listening on.

  • database: the name of the database to connect to.

  • user: the username to sign-on as.

  • password: the password to authenticate with.

 

Running Client Binaries

 

Log Directory

The log directory is specified by the NAVDB_CLIENT_LOG environment variable.

If building and running from source then this environment variable can be found in the relevant setup script, otherwise you should set it yourself before running any of the client binaries, including programs you build using the client libraries.

 

Command-line Arguments

All example binaries take an optional connect-string as the first parameter.

 

PHP Extension Note

Enable dynamically loaded PHP libraries by setting enable_dl = On in php.ini.

 

Build Requirements

Source for the NavDB client utilities and libraries can be found at the NavDB Clients GitHub repository.

 

C client

  • C compiler and a C++ compiler and linker:

    • Linux: GCC and G++ 7.2

    • Mac OS X: Clang 5.0

    • Visual Studio 2017 Command Line Tools (Windows)

  • CMake 3.10+

  • Make 3.81+

  • C++ build requirements

 

C++ client and utilities

  • C++ compiler and linker:

    • Linux: GCC and G++ 7.2

    • Mac OS X: Clang 5.0

    • Visual Studio 2017 Command Line Tools (Windows)

  • CMake 3.10+

  • Make 3.81+

  • Boost 1.69.0

 

Java client

  • JDK 8+

  • Swig 3

  • C++ build requirements

 

Python client

  • Python 3.6.2+

  • NumPy 1.13.1+

  • Swig 3

  • C++ build requirements

 

PHP 7 client

  • PHP 7.0+

  • Swig 3

  • C++ build requirements

 

Additional Windows Specific build requirements

  • 7zip

  • Build Boost 1.69.0 from source using this setup.

 

Additional Documentation build requirements

  • Asciidoctor

 

Mac/Linux Development Environment Setup

Steps:

  • In your profile script set an environment variable called NAVDB_DEV_ROOT which points to the path containing the NavDB client (which should preferably be called navdb), e.g.: /opt/navdb. This variable can also be set at the top of the setup script you use before building (see the next step).

  • Ensure that all scripts under client/scripts are executable, e.g.:

cd client
find -name "*.sh" | xargs chmod u+x *.sh
  • Edit the appropriate setup script under clients/scripts (either setup_linux.sh or setup_macosx.sh) and set the BOOST_XXX environment variables (where Boost library and include files can be found).

  • For Linux source the setup-linux.sh script

. ./setup-linux.sh
  • For Mac OS X source the setup-macosx.sh script:

. ./setup-macosx.sh

 

Windows setup using Visual Studio 2017 Command Line Tools

Steps:

  • Add a new environment variable for NAVDB_DEV_ROOT which points to the path containing the NavDB client (which should preferably be called navdb), e.g.: C:\navdb.

  • Add binary directories to PATH for:

    • Swig

    • 7Zip

  • Run the x64 Developer Command Prompt (for Visual Studio 2017 Command Line Tools) from the Start menu and use this to build the client with Visual Studio 2017 Command Line Tools.

  • Run setup-win64.bat under the client\scripts directory.

 

Build Notes

 

Building the Client Source

  • Under the client/scripts directory are setup scripts that must be edited and run prior to building the source (see the previous section).

  • Run the full-client-build(.sh/.bat) script to build the client libraries.

  • Optionally run the full-example-build(.sh/.bat) script to build the examples.

  • Run the install(.sh/.bat) script.

  • You can find the compiled binaries and libraries under NAVDB_CLIENT_BIN.

 

Building individual Client Drivers

  • Each client driver (under client/lang-clients) has a scripts directory that contains build, clean and install scripts.

  • The C++ client is a requirement for all other clients.

 

C and C++ Clients

  • The C and C++ clients utilize CMake to generate Makefiles.

  • The C client wraps the C++ library using wrapper techniques.

 

Java Client

  • The Java client uses Swig to wrap the C++ library.

  • When running the Java test program ensure that:

    • The CLASSPATH includes lib/navdb_java_client.jar.

    • The lib directory is specified for java.library.path.

 

Python Client

  • The Python client uses Swig to wrap the C++ library.

  • When running the Python test program ensure that:

    • The lib directory is added to LD_LIBRARY_PATH so that the shared library starting with _navdb_python_client can be found.

 

PHP 7 Client

  • The PHP 7 client uses Swig to wrap the C++ library.

 

Copyright 2017 and onwards Navigator Data (Pty) Ltd.

Client code licensed under the Apache License, Version 2.0: