Documentation, build and test updates

asg017 · Aug 8, 2022 · 4cc78dc · 4cc78dc
1 parent 8e84504
commit 4cc78dc
Show file tree

Hide file tree

Showing 8 changed files with 740 additions and 340 deletions.
diff --git a/Makefile b/Makefile
@@ -1,27 +1,25 @@
 COMMIT=$(shell git rev-parse HEAD)
 VERSION=$(shell git describe --tags --exact-match --always)
-VERSION=v0.0.0
+VERSION=$(shell cat VERSION)
 DATE=$(shell date +'%FT%TZ%z')
 
 GO_BUILD_LDFLAGS=-ldflags '-X main.Version=$(VERSION) -X main.Commit=$(COMMIT) -X main.Date=$(DATE)' 
 GO_BUILD_NO_NET_LDFLAGS=-ldflags '-X main.Version=$(VERSION) -X main.Commit=$(COMMIT) -X main.Date=$(DATE) -X main.OmitNet=1'
 GO_BUILD_CGO_CFLAGS=CGO_CFLAGS=-DSQLITE3_INIT_FN=sqlite3_http_init
 GO_BUILD_NO_NET_CGO_CFLAGS=CGO_CFLAGS=-DSQLITE3_INIT_FN=sqlite3_httpnonet_init
 
-CGO_CFLAGS="-DSQLITE3_INIT_FN=sqlite3_httpnonet_init"
-
-ifeq ($(OS),Windows_NT)
-CONFIG_WINDOWS=y
-endif
-
 ifeq ($(shell uname -s),Darwin)
 CONFIG_DARWIN=y
+else ifeq ($(OS),Windows_NT)
+CONFIG_WINDOWS=y
 else
 CONFIG_LINUX=y
 endif
-
+
+# framework stuff is needed bc https://github.com/golang/go/issues/42459#issuecomment-896089738
 ifdef CONFIG_DARWIN
 LOADABLE_EXTENSION=dylib
+SQLITE3_CFLAGS=-framework CoreFoundation -framework Security
 endif
 
 ifdef CONFIG_LINUX
@@ -40,9 +38,7 @@ TARGET_OBJ=dist/http0.o
 TARGET_SQLITE3=dist/sqlite3
 
 loadable: $(TARGET_LOADABLE) $(TARGET_LOADABLE_NO_NET)
-sqlite3: $(TARGET_SQLITE3)
-package: $(TARGET_PACKAGE)
-all: loadable sqlite3 package
+all: loadable 
 
 $(TARGET_LOADABLE):  $(shell find . -type f -name '*.go')
 	$(GO_BUILD_CGO_CFLAGS) go build \
@@ -61,18 +57,6 @@ $(TARGET_OBJ):  $(shell find . -type f -name '*.go')
 	$(GO_BUILD_LDFLAGS) \
 	-o $@ .
 
-# framework stuff is needed bc https://github.com/golang/go/issues/42459#issuecomment-896089738
-$(TARGET_SQLITE3): $(TARGET_OBJ) dist/sqlite3-extra.c sqlite/shell.c
-	gcc \
-	-framework CoreFoundation -framework Security \
-	dist/sqlite3-extra.c sqlite/shell.c $(TARGET_OBJ) \
-	-L. -Isqlite \
-	-DSQLITE_EXTRA_INIT=core_init -DSQLITE3_INIT_FN=sqlite3_http_init \
-	-o $@
-
-$(TARGET_PACKAGE): $(TARGET_LOADABLE) $(TARGET_OBJ) sqlite/sqlite-http.h $(TARGET_SQLITE3)
-	zip --junk-paths $@ $(TARGET_LOADABLE) $(TARGET_OBJ) sqlite/sqlite-http.h $(TARGET_SQLITE3)
-
 dist/sqlite3-extra.c: sqlite/sqlite3.c sqlite/core_init.c
 	cat sqlite/sqlite3.c sqlite/core_init.c > $@
 
@@ -94,4 +78,4 @@ test-watch:
 
 .PHONY: all format clean \
 	test test-watch httpbin \
-	loadable sqlite3
+	loadable
diff --git a/README.md b/README.md
@@ -2,45 +2,78 @@
 
 A SQLite extension for making HTTP requests purely in SQL.
 
-- Create GET, POST, or any other HTTP requests and download responses, like `curl`, `wget`, and `fetch`
+- Create GET, POST, or other HTTP requests and download responses, like `curl`, `wget`, and `fetch`
 - Query HTTP headers, cookies, timing information
 - Set rate limits, timeouts
 
-## 🚧🚧 Work In Progress! 🚧🚧
+## Usage
 
-This library is experimental and subject to change. I plan to make a stable beta release and subsequent v0+v1 in the near future, so use with caution.
+```sql
+.load ./http0
+select http_get_body('https://text.npr.org/');
+/*
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <title>NPR : National Public Radio</title>
+  ....
+*/
+```
+
+## Documentation
 
-When v0 is ready (with a mostly stable API), I will make a release (so watch this repo for that) and will make a blog post, feel free to [follow me on twitter](https://twitter.com/agarcia_me) to get notified of that.
+See [`docs.md`](./docs.md) for a full API reference.
 
 ## Installing
 
-`sqlite-http` is distributed as a [runtime-loadable](https://www.sqlite.org/loadext.html) SQLite extension. Depending on your operating system, you'll need to either download the compiled `.dylib`, `.so`, or `.dll` file and load it
-into your SQLite environment.
+The [Releases page](https://github.com/asg017/sqlite-lines/releases) contains pre-built binaries for Linux amd64, MacOS amd64 (no arm), and Windows.
 
-TODO document release download
+### As a loadable extension
 
-For example, if you plan on using it on the command line using `sqlite3`:
+If you want to use `sqlite-http` as a [Runtime-loadable extension](https://www.sqlite.org/loadext.html), Download the `http0.dylib` (for MacOS), `http0.so` (Linux), or `http0.dll` (Windows) file from a release and load it into your SQLite environment.
 
-```bash
-sqlite> .load ./http0
-sqlite> select http_get("...");
+> **Note:**
+> The `0` in the filename (`http0.dylib`/ `http0.so`/`http0.dll`) denotes the major version of `sqlite-http`. Currently `sqlite-http` is pre v1, so expect breaking changes in future versions.
+
+For example, if you are using the [SQLite CLI](https://www.sqlite.org/cli.html), you can load the library like so:
+
+```sql
+.load ./http0
+select http_version();
+-- v0.0.1
 ```
 
-Note: by default, the `sqlite3` CLI pre-installed on MacOS systems don't allow for loading extensions, so try downloading another version (ex. from [brew](https://formulae.brew.sh/formula/sqlite)) to use `sqlite-http` properly on Mac.
+Or in Python, using the builtin [sqlite3 module](https://docs.python.org/3/library/sqlite3.html):
 
-## Documentation
+```python
+import sqlite3
 
-See [`api.md`](./api.md) for a full API reference.
+con = sqlite3.connect(":memory:")
 
-## Examples
+con.enable_load_extension(True)
+con.load_extension("./http0")
 
-First, let's load the extension using the [`.load`](https://www.sqlite.org/cli.html#loading_extensions) command in SQLite's CLI.
+print(con.execute("select http_version()").fetchone())
+# ('v0.0.1',)
+```
 
-```sql
-.load http0.so
+Or in Node.js using [better-sqlite3](https://github.com/WiseLibs/better-sqlite3):
+
+```javascript
+const Database = require("better-sqlite3");
+const db = new Database(":memory:");
+
+db.loadExtension("./lines0");
+
+console.log(db.prepare("select http_version()").get());
+// { 'http_version()': 'v0.0.1' }
 ```
 
-> Note: Loading extensions may be disabled by default in your computer's builtin `sqlite3` CLI. Consider downloading a [newer version of SQLite](https://sqlite.org/download.html). Also look into your favorite SQLite client library API for how to load extensions, like Python's [`load_extension`](https://docs.python.org/3/library/sqlite3.html#sqlite3.Connection.load_extension), Node.js's [`loadExtesion`](https://github.com/JoshuaWise/better-sqlite3/blob/master/docs/api.md#loadextensionpath-entrypoint---this) in `better-sqlite`, or the [`load_extension`](https://www.sqlite.org/lang_corefunc.html#load_extension) function in some SQLite libraries.
+Or with [Datasette](https://datasette.io/) TODO:
+
+```
+datasette data.db --load-extension ./http0
+```
 
 ## Testing
 
@@ -53,6 +86,6 @@ SKIP_DO=1; python3 test.py
 ## See also
 
 - [sqlite-html](https://github.com/asg017/sqlite-html), for parsing and querying HTML using CSS selectors in SQLite (pairs great with this tool)
-- [pgsql-http](https://github.com/pramsey/pgsql-http), a similar yet very different HTTP libraryt for POstgreSQL (didn't know about this before I started this, but interestingly enough came up with a very similar API)
+- [pgsql-http](https://github.com/pramsey/pgsql-http), a similar yet very different HTTP library for POstgreSQL (didn't know about this before I started this, but interestingly enough came up with a very similar API)
 - [riyaz-ali/sqlite](https://github.com/riyaz-ali/sqlite), the brilliant Go library that this library depends on
 - [nalgeon/sqlean](https://github.com/nalgeon/sqlean), several pre-compiled handy SQLite functions, in C