Installing the kRPC C-nano client library
=========================================

Via vcpkg
---------

The library is published to the vcpkg registry, so it can be installed without
this archive:

On Linux:

    vcpkg install krpc-cnano

On Windows:

    vcpkg install krpc-cnano:x64-windows

The library communicates over a serial port unless a transport feature is asked
for. The "tcp" feature builds it to communicate over TCP/IP instead:

    vcpkg install "krpc-cnano[tcp]"
    vcpkg install "krpc-cnano[tcp]:x64-windows"

The "localsocket" feature builds it to communicate over a unix domain socket
with a server on the same machine, which is available on Linux, macOS, and
Windows 10 1803 and later:

    vcpkg install "krpc-cnano[localsocket]"
    vcpkg install "krpc-cnano[localsocket]:x64-windows"

Then pass the vcpkg toolchain file when configuring your CMake project:

    cmake -B build -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake

And link the library in your CMakeLists.txt:

    find_package(krpc_cnano CONFIG REQUIRED)
    target_link_libraries(my_app PRIVATE krpc_cnano::krpc_cnano)


Via CMake
---------

Requirements
------------

 * CMake 3.15 or later
 * A C99-compatible compiler
 * protoc (the protobuf compiler)
 * Python 3 (used by the nanopb generator at build time)

By default, CMake looks for a system-installed nanopb with CMake config support.
Alternatively, CMake can download nanopb automatically via FetchContent — see
"Using FetchContent for dependencies" below.


Building and installing
-----------------------

    cmake -B build
    cmake --build build
    sudo cmake --install build
    sudo ldconfig

To install to a custom location, pass CMAKE_INSTALL_PREFIX:

    cmake -B build -DCMAKE_INSTALL_PREFIX=/install/path
    cmake --build build
    cmake --install build


Using FetchContent for dependencies
------------------------------------

To download nanopb automatically at build time instead of using a system
package, pass KRPC_FETCH_DEPS=ON:

    cmake -B build -DKRPC_FETCH_DEPS=ON
    cmake --build build
    sudo cmake --install build

The fine-grained option KRPC_FETCH_NANOPB=ON is also accepted. When an option
is OFF (the default), the system package is required and CMake will error if it
cannot be found.


Choosing the transport
----------------------

By default the library communicates with the server over a serial port, using
the API of the platform it is built for. To communicate over TCP/IP with a
server reachable over the network, pass KRPC_COMMUNICATION_TCP=ON:

    cmake -B build -DKRPC_COMMUNICATION_TCP=ON
    cmake --build build
    sudo cmake --install build

Ask for it this way rather than by defining KRPC_COMMUNICATION_TCP directly, so
that programs linking the library are built for the same transport and, on
Windows, are linked against winsock along with it. A connection is then opened
with the address and port the server is listening on, in place of the name of a
port.


Using the installed library
---------------------------

After installation, downstream CMake projects can locate the library with:

    find_package(krpc_cnano CONFIG REQUIRED)
    target_link_libraries(my_target PRIVATE krpc_cnano::krpc_cnano)
