Prepare for crates.io publishing

Author: simolus3

crates/core/Cargo.toml

@@ -7,6 +7,8 @@ repository.workspace = true
 license.workspace = true
 authors.workspace = true
 keywords.workspace = true
+description = "The PowerSync SQLite extension"
+readme = "README.md"
 
 [lib]
 name = "powersync_core"

crates/core/README.md

@@ -1,8 +1,24 @@
+<p align="center">
+  <a href="https://www.powersync.com" target="_blank"><img src="https://github.com/powersync-ja/.github/assets/7372448/d2538c43-c1a0-4c47-9a76-41462dba484f"/></a>
+</p>
+
+_[PowerSync](https://www.powersync.com) is a sync engine for building local-first apps with instantly-responsive UI/UX and simplified state transfer. Syncs between SQLite on the client-side and Postgres, MongoDB or MySQL on the server-side._
+
 # powersync_core
 
-This is the core SQLite extension, containing all the logic.
+This is the core SQLite extension, containing all the logic. This is used internally by PowerSync SDKs,
+and would typically not be used by users directly.
+
+The role of the extension is to create user-defined functions that higher-level SDKs would use to implement
+schema management and a PowerSync client.
+Not all of this is documented, but [this directory](https://github.com/powersync-ja/powersync-sqlite-core/tree/main/docs)
+provides some hints on how a custom PowerSync SDK could be implemented.
 
-Since the different build configurations (loadable extension, bundled SQLite shell)
-use different cargo config, we can't completely separate them just using features.
-Instead, we use different crates depending on this core lib.
+For this reason, the crate doesn't have much of a public API. In the default build mode, it doesn't expect
+SQLite to be linked and exposes a single function: `sqlite3_powersync_init`,
+a [loadable extension](https://sqlite.org/loadext.html) entrypoint.
 
+For applications linking SQLite, the `static` feature of this crate can be enabled.
+With that feature, `powersync_init_static()` can be called to load the
+extension for all new connections.
+The application is responsible for linking SQLite in that case.

crates/core/src/lib.rs

@@ -35,6 +35,10 @@ mod view_admin;
 mod views;
 mod vtab_util;
 
+/// The entrypoint for the PowerSync SQLite core extension.
+///
+/// When compiling this Rust crate into a dynamic library, it can be used by embedders to load it
+/// through [SQLite's opening mechanism](https://sqlite.org/loadext.html#loading_an_extension).
 #[unsafe(no_mangle)]
 pub extern "C" fn sqlite3_powersync_init(
     db: *mut sqlite::sqlite3,
@@ -85,7 +89,7 @@ fn init_extension(db: *mut sqlite::sqlite3) -> Result<(), PowerSyncError> {
 unsafe extern "C" {
     #[cfg(feature = "static")]
     #[allow(non_snake_case)]
-    pub fn sqlite3_auto_extension(
+    fn sqlite3_auto_extension(
         xEntryPoint: Option<
             extern "C" fn(
                 *mut sqlite::sqlite3,
@@ -96,6 +100,10 @@ unsafe extern "C" {
     ) -> ::core::ffi::c_int;
 }
 
+/// Calls `sqlite3_auto_extension` with [sqlite3_powersync_init] to automatically load
+/// the PowerSync core extension into new connections.
+///
+/// For details, see https://sqlite.org/loadext.html#statically_linking_a_run_time_loadable_extension
 #[cfg(feature = "static")]
 #[unsafe(no_mangle)]
 pub extern "C" fn powersync_init_static() -> c_int {

crates/sqlite_nostd/Cargo.toml

@@ -7,6 +7,8 @@ repository.workspace = true
 license.workspace = true
 authors.workspace = true
 keywords.workspace = true
+description = "Lightweight, semi-unsafe, nostd bindings to sqlite3"
+readme = "README.md"
 
 [lib]
 name = "powersync_sqlite_nostd"