History

Nick Craig-Wood e43b5ce5e5 Remove github.com/pkg/errors and replace with std library version This is possible now that we no longer support go1.12 and brings rclone into line with standard practices in the Go world. This also removes errors.New and errors.Errorf from lib/errors and prefers the stdlib errors package over lib/errors.		2021-11-07 11:53:30 +00:00
..
ctest	librclone: add tests for build and execute them in the actions #4891	2021-04-28 16:55:08 +01:00
gomobile	librclone: factor into gomobile and internal implementation #4891	2021-04-28 16:55:08 +01:00
librclone	Remove github.com/pkg/errors and replace with std library version	2021-11-07 11:53:30 +00:00
python	librclone: free strings in python example	2021-11-01 12:36:52 +00:00
README.md	Add mention of Rust bindings for `librclone`	2021-11-01 12:43:31 +00:00
librclone.go	docs/librclone: document that strings are utf8 encoded	2021-11-01 12:39:00 +00:00

README.md

librclone

This directory contains code to build rclone as a C library and the shims for accessing rclone from C and other languages.

Note for the moment, the interfaces defined here are experimental and may change in the future. Eventually they will stabilse and this notice will be removed.

C

The shims are a thin wrapper over the rclone RPC.

Build a shared library like this:

go build --buildmode=c-shared -o librclone.so github.com/rclone/rclone/librclone

Build a static library like this:

go build --buildmode=c-archive -o librclone.a github.com/rclone/rclone/librclone

Both the above commands will also generate librclone.h which should be #included in C programs wishing to use the library.

The library will depend on libdl and libpthread.

Documentation

For documentation see the Go documentation for:

C Example

There is an example program ctest.c with Makefile in the ctest subdirectory.

gomobile

The gomobile subdirectory contains the equivalent of the C binding but suitable for using with gomobile using something like this.

gomobile bind -v -target=android -javapkg=org.rclone github.com/rclone/rclone/librclone/gomobile

The command generates an Android library (aar) that can be imported into an Android application project. Librclone will be contained within libgojni.so and loaded automatically.

// imports
import org.rclone.gomobile.Gomobile;
import org.rclone.gomobile.RcloneRPCResult;

// initialize rclone
Gomobile.rcloneInitialize();

// call RC method and log response.
RcloneRPCResult response = Gomobile.rcloneRPC("core/version", "{}");
Log.i("rclone", "response status: " + response.getStatus());
Log.i("rclone", "output: " + response.getOutput());

// Clean up when finished.
Gomobile.rcloneFinalize();

This is a low level interface - serialization, job management etc must be built on top of it.

iOS has not been tested (but should probably work).

Further docs:

gomobile main website
gomobile wiki
go issue #16876 where the feature was added
gomobile design doc for extra details not in the docs.

python

The python subdirectory contains a simple Python wrapper for the C API using rclone linked as a shared library with ctypes.

You are welcome to use this directly.

This needs expanding and submitting to pypi...

Rust

Rust bindings are available in the librclone crate: https://crates.io/crates/librclone

TODO

Async jobs must currently be cancelled manually at the moment - RcloneFinalize doesn't do it.
This will use the rclone config system and rclone logging system.
Need examples showing how to configure things,