rclone/librclone/README.md

3.2 KiB

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:

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,