Let’s Build Couchbase Lite .NET: Part 1, .NET Core

This is the first entry in an ongoing series about building Couchbase Lite .NET from source.  As I mentioned in my last post, I am too close and familiar with the library and I often forget that it is complicated and annoying to build without the amount of full time work that I have spent with it.  This entry will feature .NET Core as the target.

Part 1: .NET Core
Part 2: UWP
Part 3: Xamarin Android
Part 4: Xamarin iOS
Part X: Generic

Couchbase Lite will work in any version of .NET Core (it can target 1.0) in theory (i.e. I didn’t test it with .NET Core 2.0 yet but if Microsoft is only expanding then it should work!).  Officially, we are going to support macOS (.NET Core supports 10.11+), Windows (.NET Core supports Windows 7 SP1 and higher), Ubuntu (.NET Core supports 64-bit 14.04, 16.04 and 16.10) and possibly CentOS (.NET Core supports 64-bit 7.1).  These instructions should in theory work with .NET Framework 4.6.1+ but that is not something we explicitly test right now.  The same supported systems would apply except macOS 10.9+ would be supported (via Mono.Framework) instead of 10.11+.

As I laid out in my previous entry, this means that we need native builds for each of these (except for Ubuntu vs CentOS which we will provide all dependencies in the Nuget package except for Glibc, and possibly libz) .  So we will start at the beginning of the list.

macOS native

In the vendor/couchbase-lite-core/build_cmake/scripts folder there is a script to build the native libraries, but let’s break down what it does.  This build makes use of CMake, which is a tool to generate various types of projects.  CMake is not a tool for directly building, but rather for setting things up to build.  In this case, it will generate Unix-style Makefiles.  The build consists of two steps:

  1. Run CMake
  2. Run make

Running CMake means running the command

cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo <path/to/source>

This will set everything up to be built.  The second step consists of the command

make -j8 LiteCore #Or whatever degree of parallelism you prefer

This will uses 8 parallel jobs to compile and link the final product that will be used on macOS:  libLiteCore.dylib (libsqlcipher.dylib may be added later).

Windows native

A note before we get started, these are not the instructions for Universal Windows Platform.  Those instructions will be in another post.  Builds made like this will not function on any version of UWP except the newest.  In the vendor/couchbase-lite-core/build_cmake/scripts folder there is a script to build the native libraries, but let’s break down what it does.  This build makes use of CMake, which is a tool to generate various types of projects.  CMake is not a tool for directly building, but rather for setting things up to build.  In this case, it will generate a Visual Studio 2015 project (it could also generate 2017, but I am hesitant to move it just yet).  The build consists of two steps:

  1. Run CMake
  2. Run msbuild

Running CMake means running this command from any Command or Powershell prompt:

& 'C:\Program Files\CMake\bin\cmake.exe' -G "Visual Studio 14 2015 <arch>"

<arch> here consists of either a blank string (x86), Win64 (x64) or ARM (32-bit ARM).  In reality we only build x86 and x64 because .NET Core does not yet run on ARM (it looks like it will in .NET Core 2.0, so this could be added later).  So each architecture needs its own folder, but after that you can run the same command in each folder to build.  You have one of two choices.  You can either run the following from a developer command prompt

msbuild LiteCore.sln /p:Configuration=RelWithDebInfo /t:LiteCore

Or you can run the following from a normal command or powershell prompt

& 'C:\Program Files\CMake\bin\cmake.exe' --build . --target LiteCore --config RelWithDebInfo

After that you will find the two final products in the RelWithDebInfo folder:  LiteCore.dll and sqlite3.dll (may become sqlcipher.dll later).

Warning: LiteCore.dll needs either Visual Studio 2015 installed, or the Visual C++ 2015 redistributable to be installed on the target machine in order to run as it makes use of shared C++ runtime functions.

Ubuntu 14.04 native

In the vendor/couchbase-lite-core/build_cmake/scripts folder there is a script to build the native libraries, but let’s break down what it does.  This build makes use of CMake, which is a tool to generate various types of projects.  CMake is not a tool for directly building, but rather for setting things up to build.  In this case, it will generate Unix-style Makefiles.  The build consists of two steps:

  1. Run CMake
  2. Run make

Running CMake means running the command

CC=clang CXX=clang++ cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DLITECORE_BUILD_SQLITE=1 <path/to/source>

As you might have gathered from the above, GCC is not supported for building LiteCore and clang should be used in conjunction with libc++.  Right now there are various dependencies that need to be installed onto the system, but the build team is working on getting those packaged into our dependency repo.  You will need to install things such as:  libatomic (part of gcc / libgcc), libbsd, libcrypto (from OpenSSL, but this dependency is likely going away in favor of mbed TLS by ARM), libc++, libz (usually comes with the OS), and maybe some others that I can’t recall right now.  Both the build and QE team separately came up with a docker container that contains the needed deps, and I will look into sharing that if there is enough interest.

After that, building is the same as macOS

make -j8 LiteCore #Or whatever degree of parallelism you prefer

This will output the final two products:  libLiteCore.so and libsqlite3.so (May become libsqlcipher.so later).


All of the above are needed to begin building for .NET Core completely (i.e. the Packaging configuration), but if you just want to try it out you can use Debug or Release and the project will only look for the libraries needed on the machine doing the build.  There are two projects to build for C#:  Couchbase.Lite and Couchbase.Lite.Support.NetDesktop.  The latter is what holds the native libraries and expects them to be in the following directories:

  • Windows x86: vendor\couchbase-lite-core\build_cmake\x86\RelWithDebInfo\
  • Windows x64: vendor\couchbase-lite-core\build_cmake\x64\RelWithDebInfo\
  • macOS: vendor\couchbase-lite-core\build_cmake\
  • Linux: vendor\couchbase-lite-core\build_cmake\

The libraries make use of C# 7 so a C# 7 compatible compiler is needed (That means a modern version of Mono or Microsoft’s toolchain).  This part of the build is trivial compared to the native side.  You can build from the command line via msbuild and target the two above projects, or build from inside the IDE.  The build should take only a very little amount of time.


If you are looking to package, the nuspec files are all in the packaging/nuget directory.  The nuspec files are not set up to build from source so you need to build everything first.  After that you can take some cues from the do_package.bat script and run the following:

nuget pack couchbase-lite.nuspec /BasePath ..\.. /Properties version=2.0.0
nuget pack couchbase-lite-support-netdesktop.nuspec /BasePath ..\.. /Properties version=2.0.0

This will output two Nuget packages and they will be the same as what you find in whatever Nuget feed you acquire Couchbase Lite from.

Warning: Due to a Nuget bug, the nuspec files must change the paths from using backslash ( \ ) to using forward slash ( / ) if Nuget is run on a non-Windows machine.  It sucks, but there is nothing I can do about that.


Hopefully this article will be useful for anyone attempting to build from source, as I encourage everyone to do since this is an open source product and the fastest way to get an issue fixed is to point out as specifically as possible where it is ;).

Advertisements

4 thoughts on “Let’s Build Couchbase Lite .NET: Part 1, .NET Core

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s