diff --git a/cozo-lib-wasm/README.md b/cozo-lib-wasm/README.md new file mode 100644 index 00000000..6c1fea77 --- /dev/null +++ b/cozo-lib-wasm/README.md @@ -0,0 +1,79 @@ +# Cozo in web assembly + +This crate provides Cozo web assembly modules for the web. +If you are targeting NodeJS, use [this](../cozo-lib-nodejs) instead: in the case of Cozo, +native code is still _much_ faster than WASM. + +## Installation + +``` +npm install cozo-lib-wasm +``` + +Alternatively, you can download `cozo_wasm--wasm32-unknown-unknown.zip` +from the [release page](https://github.com/cozodb/cozo/releases) and include +the JS and WASM files directly in your project: see the `index.html` example +[here](https://rustwasm.github.io/docs/wasm-bindgen/examples/without-a-bundler.html) for +what is required in your code. + +## Usage + +See the code [here](wasm-react-demo/src/App.js). Basically, you write + +```js +import init, {CozoDb} from "cozo-lib-wasm"; +``` + +and call + +```js +let db; +init().then(() => { + db = CozoDb.new(); + // db can only be used after the promise resolves +}) +``` + +## API + +```ts +export class CozoDb { + free(): void; + + static new(): CozoDb; + + run(script: string, params: string): string; + + export_relations(data: string): string; + + import_relations(data: string): string; +} +``` + +Note that this API is synchronous. If your computation runs for a long time, +**it will block the main thread**. If you know that some of your queries are going to be heavy, +you should consider running Cozo in a web worker. However, the published module +may not work across browsers in web workers (look for the row "Support for ECMAScript +modules" [here](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker#browser_compatibility)). + +The next section contains some pointers for how to alleviate this, but expect a lot of work. + +## Compiling + +You will need to install [Rust](https://rustup.rs/), [NodeJS with npm](https://nodejs.org/), +and [wasm-pack](https://github.com/rustwasm/wasm-pack) first. + +The published module was built with + +```bash +wasm-pack build --target web --release +``` + +and the environment variable `CARGO_PROFILE_RELEASE_LTO=fat`. + +The important option is `--target web`: the above usage instructions only work for this target. +See the documentation [here](https://rustwasm.github.io/wasm-pack/book/commands/build.html#target). + +if you are interested in running Cozo in a web worker and expect it to run across browsers, +you will need to use the `--target no-modules` option, and write a lot of gluing code. +See [here](https://rustwasm.github.io/wasm-bindgen/examples/wasm-in-web-worker.html) for tips. \ No newline at end of file diff --git a/cozo-lib-wasm/wasm-react-demo/README.md b/cozo-lib-wasm/wasm-react-demo/README.md index 58beeacc..99d40706 100644 --- a/cozo-lib-wasm/wasm-react-demo/README.md +++ b/cozo-lib-wasm/wasm-react-demo/README.md @@ -1,70 +1,4 @@ -# Getting Started with Create React App +# Cozo in WASM demo -This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app). - -## Available Scripts - -In the project directory, you can run: - -### `npm start` - -Runs the app in the development mode.\ -Open [http://localhost:3000](http://localhost:3000) to view it in your browser. - -The page will reload when you make changes.\ -You may also see any lint errors in the console. - -### `npm test` - -Launches the test runner in the interactive watch mode.\ -See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information. - -### `npm run build` - -Builds the app for production to the `build` folder.\ -It correctly bundles React in production mode and optimizes the build for the best performance. - -The build is minified and the filenames include the hashes.\ -Your app is ready to be deployed! - -See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information. - -### `npm run eject` - -**Note: this is a one-way operation. Once you `eject`, you can't go back!** - -If you aren't satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project. - -Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you're on your own. - -You don't have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn't feel obligated to use this feature. However we understand that this tool wouldn't be useful if you couldn't customize it when you are ready for it. - -## Learn More - -You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started). - -To learn React, check out the [React documentation](https://reactjs.org/). - -### Code Splitting - -This section has moved here: [https://facebook.github.io/create-react-app/docs/code-splitting](https://facebook.github.io/create-react-app/docs/code-splitting) - -### Analyzing the Bundle Size - -This section has moved here: [https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size](https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size) - -### Making a Progressive Web App - -This section has moved here: [https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app](https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app) - -### Advanced Configuration - -This section has moved here: [https://facebook.github.io/create-react-app/docs/advanced-configuration](https://facebook.github.io/create-react-app/docs/advanced-configuration) - -### Deployment - -This section has moved here: [https://facebook.github.io/create-react-app/docs/deployment](https://facebook.github.io/create-react-app/docs/deployment) - -### `npm run build` fails to minify - -This section has moved here: [https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify](https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify) +This is the source code for the demo at https://cozodb.github.io/wasm-demo/. +It might be helpful if you want to integrate Cozo WASM in your own project. \ No newline at end of file diff --git a/scripts/build-release-mac.sh b/scripts/build-release-mac.sh index 8a7e8393..9ebdf1f6 100755 --- a/scripts/build-release-mac.sh +++ b/scripts/build-release-mac.sh @@ -40,3 +40,5 @@ cd .. cd cozo-lib-wasm CARGO_PROFILE_RELEASE_LTO=fat ./build.sh cd .. + +zip release/cozo_wasm-$VERSION-wasm32-unknown-unknown.zip $(find cozo-lib-wasm/pkg) \ No newline at end of file