rclone/librclone
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
librclone.go docs/librclone: document that strings are utf8 encoded 2021-11-01 12:39:00 +00:00
README.md Add mention of Rust bindings for librclone 2021-11-01 12:43:31 +00:00

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,