Skip to content

Commit a13c7af

Browse files
undecafundecaf
committed
Improve documentation
1 parent 8f3207d commit a13c7af

File tree

7 files changed

+76
-62
lines changed

7 files changed

+76
-62
lines changed

‎README.md‎

Lines changed: 66 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ of the [ZBar Bar Code Reader](https://github.com/mchehab/zbar) written in C/C++.
2323
RGB/grayscale [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) objects
2424
+ Outperforms pure JavaScript barcode scanners
2525

26-
:warning: v0.10.0 contains breaking changes regarding bundling, please refer to section [Bundling/deploying zbar-wasm](#bundlingdeploying-zbar-wasm).
26+
:warning: zbar-wasm version 0.10 contains breaking changes with respect to version 0.9, please refer to section [Bundling/deploying zbar-wasm](#bundlingdeploying-zbar-wasm).
2727

2828

2929
## Examples based on zbar-wasm
@@ -54,7 +54,7 @@ An example that scans a static image file:
5454
<pre id="result"></pre>
5555

5656
<script type="module">
57-
import * as zbarWasm from 'https://cdn.jsdelivr.net/npm/@undecaf/[email protected].0/dist/main.js'
57+
import * as zbarWasm from 'https://cdn.jsdelivr.net/npm/@undecaf/[email protected].1/dist/index.js'
5858
5959
(async () => {
6060
const
@@ -88,15 +88,15 @@ Almost identical to the snippet above, just replace the lines
8888
```html
8989
⁝
9090
<script type="module">
91-
import * as zbarWasm from 'https://cdn.jsdelivr.net/npm/@undecaf/[email protected].0/dist/main.js'
91+
import * as zbarWasm from 'https://cdn.jsdelivr.net/npm/@undecaf/[email protected].1/dist/index.js'
9292
⁝
9393
```
9494
9595
with
9696
9797
```html
9898
⁝
99-
<script src="https://cdn.jsdelivr.net/npm/@undecaf/[email protected].0/dist/index.js"></script>
99+
<script src="https://cdn.jsdelivr.net/npm/@undecaf/[email protected].1/dist/index.js"></script>
100100
<script>
101101
⁝
102102
```
@@ -107,9 +107,9 @@ with
107107
Installing:
108108
109109
```shell script
110-
$ npm install @undecaf/zbar-wasm@0.10.0
110+
$ npm install @undecaf/zbar-wasm@0.10.1
111111
or
112-
$ yarn add @undecaf/zbar-wasm@0.10.0
112+
$ yarn add @undecaf/zbar-wasm@0.10.1
113113
```
114114
115115
Using:
@@ -135,10 +135,9 @@ import { scanImageData } from '@undecaf/zbar-wasm';
135135
136136
const
137137
imageData = ctx.getImageData(0, 0, img.width, img.height),
138-
// @ts-ignore
139138
symbols = await scanImageData(imageData);
140139
141-
console.log(symbols[0]?.typeName, symbols[0]?.decode())
140+
console.log(ssymbols[0]?.typeName, symbols[0]?.decode())
142141
})('https://raw.githubusercontent.com/undecaf/zbar-wasm/master/tests/img/qr_code.png')
143142
```
144143
@@ -152,33 +151,46 @@ const { scanImageData } = require('@undecaf/zbar-wasm');
152151
153152
### Bundling/deploying zbar-wasm
154153
155-
zbar-wasm delegates barcode scanning to the WebAssembly code in file `zbar.wasm`.
156-
This file is part of the package and can be provided at runtime in different ways:
154+
zbar-wasm provides ESM and CommonJS modules for Node.js and browsers. One of them needs to be
155+
bundled in your application. In any case, barcode scanning is delegated to the WebAssembly code
156+
in file `zbar.wasm`. At runtime, this file can be provided in different ways depending on the
157+
bundling configuration and on which zbar-wasm module was emitted by the bundler:
157158
158159
+ It can be loaded from a CDN by browsers.
159160
+ It can be bundled as an asset. That asset should be served to browsers as `application/wasm`
160161
so that it can be compiled in parallel with being received.
161-
+ zbar-wasm also provides modules that contain `zbar.wasm` as inline data.
162-
163-
The [package entry points](https://nodejs.org/docs/latest-v16.x/api/packages.html#package-entry-points)
164-
of zbar-wasm have been chosen so that bundlers will select the
165-
appropriate module by default in most cases. `zbar.wasm` as inline data requires an
166-
[export condition](https://nodejs.org/docs/latest-v16.x/api/packages.html#conditional-exports)
167-
in the bundler configuration.
168-
169-
The build process of zbar-wasm tests bundling with
170-
[Webpack](https://webpack.js.org/), [Rollup](https://rollupjs.org/) and
171-
[esbuild](https://esbuild.github.io/) and also tests the resulting bundles.
172-
The bundler configuration files
162+
+ Several zbar-wasm modules contain `zbar.wasm` as inline data.
163+
164+
This overview shows which modules are available in zbar-wasm:
165+
166+
| Path in package | Module type | Node core modules polyfilled<br>(suitable for browsers) | `zbar.wasm` inlined |
167+
|:--------------------------|:-----------:|:-------------------------------------------------------:|:-------------------:|
168+
| `/dist/index.mjs` | ESM | :heavy_check_mark: | |
169+
| `/dist/index.js` | CommonJS | :heavy_check_mark: | |
170+
| `/dist/main.mjs` | ESM | | |
171+
| `/dist/main.cjs` | CommonJS | | |
172+
| `/dist/inlined/index.mjs` | ESM | :heavy_check_mark: | :heavy_check_mark: |
173+
| `/dist/inlined/index.js` | CommonJS | :heavy_check_mark: | :heavy_check_mark: |
174+
| `/dist/inlined/main.mjs` | ESM | | :heavy_check_mark: |
175+
| `/dist/inlined/main.cjs` | CommonJS | | :heavy_check_mark: |
176+
177+
The [package entry points](https://nodejs.org/docs/latest-v16.x/api/packages.html#package-entry-points) of zbar-wasm have been chosen so that bundlers will emit the
178+
appropriate module by default in most cases. However, `zbar.wasm` as inline data requires a suitable
179+
[export condition](https://nodejs.org/docs/latest-v16.x/api/packages.html#conditional-exports) in the bundler configuration, typically `'zbar-inlined'`.
180+
Please refer to the `exports` section of `package.json` for details.
181+
182+
[Building zbar-wasm](#building-zbar-wasm-from-source) runs bundling tests with [Webpack](https://webpack.js.org/), [Rollup](https://rollupjs.org/) and
183+
[esbuild](https://esbuild.github.io/) and also tests the resulting bundles. The bundler configuration files
173184
[`tests/{webpack,rollup,esbuild}.config.js`](https://github.com/undecaf/zbar-wasm/tree/master/tests)
174-
may be used as a reference of how to achieve a particular bundling result. They cover the following
175-
combinations of platforms, module types and `zbar.wasm` provisioning:
185+
may be used as a reference of how to achieve a particular bundling result. Each of them covers
186+
the following combinations of platforms, module types and `zbar.wasm` provisioning for the
187+
respective bundler:
176188
177-
| `zbar.wasm` | Node.js module types | Browser module types |
178-
|:------------------|:--------------------:|:---------------------:|
179-
| loaded from CDN | | ESM, plain script |
180-
| bundled as asset | ESM, CommonJS | ESM |
181-
| inlined in module | ESM, CommonJS | ESM, plain script |
189+
| `zbar.wasm` | Node module types | Browser module types |
190+
|:------------------|:-----------------:|:---------------------:|
191+
| loaded from CDN | | ESM, plain `<script>` |
192+
| bundled as asset | ESM, CommonJS | ESM |
193+
| inlined in module | ESM, CommonJS | ESM, plain `<script>` |
182194
183195
184196
## API documentation
@@ -211,32 +223,34 @@ Prerequisites:
211223
+ GNU `make`, `tar` and `curl`
212224
+ [Docker](https://www.docker.com/) or [Podman](https://podman.io/)
213225
+ [Node.js](https://nodejs.org/) v16+
226+
+ At least one of the [browsers supported by TestCafé](https://testcafe.io/documentation/402828/guides/intermediate-guides/browsers)
214227
215228
To build:
216229
217-
```bash
218-
$ git clone https://github.com/undecaf/zbar-wasm
219-
$ cd zbar-wasm
220-
$ make
221-
```
222-
223-
The `make` command runs [emscripten](https://emscripten.org/) in a container, compiling the C/C++
224-
sources of the [ZBar Bar Code Reader](https://github.com/mchehab/zbar)
225-
to [WebAssembly](https://webassembly.org/). It also compiles and bundles the TypeScript glue code
226-
and runs the tests in Node.js on the host machine.
227-
228-
If you prefer [Podman](https://podman.io/) as container engine then the provided `Makefile` needs
229-
to be edited before running `make`: replace the line
230-
231-
```
232-
EM_ENGINE = $(EM_DOCKER)
233-
```
234-
235-
with
236-
237-
```
238-
EM_ENGINE = $(EM_PODMAN)
239-
```
230+
- Clone this repository:
231+
```bash
232+
$ git clone https://github.com/undecaf/zbar-wasm
233+
$ cd zbar-wasm
234+
```
235+
- Enter your browser(s) in `.testcaferc.json` ([supported browsers](https://testcafe.io/documentation/402828/guides/intermediate-guides/browsers)).
236+
- Enter two available port numbers in `tests/src/ports.js`.
237+
- If you prefer [Podman](https://podman.io/) as container engine then replace
238+
```
239+
EM_ENGINE = $(EM_DOCKER)
240+
```
241+
with
242+
```
243+
EM_ENGINE = $(EM_PODMAN)
244+
```
245+
in the provided `Makefile`.
246+
- Run the build process:
247+
```bash
248+
$ make
249+
```
250+
The `make` command runs [emscripten](https://emscripten.org/) in a container, compiling the C/C++
251+
sources of the [ZBar Bar Code Reader](https://github.com/mchehab/zbar)
252+
to [WebAssembly](https://webassembly.org/). It also compiles and bundles the TypeScript glue code
253+
and runs the tests in Node.js and in the selected browser(s) on the host machine.
240254
241255
242256
## Credits to ...

‎docs/example/index.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ <h5>Result</h5>
6363
</div>
6464
</div>
6565

66-
<script src="https://cdn.jsdelivr.net/npm/@undecaf/[email protected].0/dist/index.js"></script>
66+
<script src="https://cdn.jsdelivr.net/npm/@undecaf/[email protected].1/dist/index.js"></script>
6767
<script src="js/main.js"></script>
6868

6969
</body>

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@undecaf/zbar-wasm",
3-
"version": "0.10.0",
3+
"version": "0.10.1",
44
"description": "A WebAssembly build of the C/C++ ZBar barcode reader",
55
"type": "module",
66
"main": "./dist/main.mjs",

‎tests/esbuild.config.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ const
1919
} = namedBuildConfigs,
2020
ZBAR_WASM_PKG_NAME = '@undecaf/zbar-wasm',
2121
// For production, set
22-
// ZBAR_WASM_REPOSITORY = `https://cdn.jsdelivr.net/npm/${ZBAR_WASM_PKG_NAME}@0.10.0`,
22+
// ZBAR_WASM_REPOSITORY = `https://cdn.jsdelivr.net/npm/${ZBAR_WASM_PKG_NAME}@0.10.1`,
2323
ZBAR_WASM_REPOSITORY = `http://localhost:${repositoryPort}`,
2424
ZBAR_WASM = `node_modules/${ZBAR_WASM_PKG_NAME}/dist/zbar.wasm`;
2525

‎tests/package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "zbar-wasm-test",
3-
"version": "0.10.0",
3+
"version": "0.10.1",
44
"type": "module",
55
"scripts": {
66
"prebuild:webpack": "rimraf build/*/webpack",
@@ -11,7 +11,7 @@
1111
"build:esbuild": "node esbuild.config.js"
1212
},
1313
"dependencies": {
14-
"@undecaf/zbar-wasm": "../undecaf-zbar-wasm-0.10.0.tgz",
14+
"@undecaf/zbar-wasm": "../undecaf-zbar-wasm-0.10.1.tgz",
1515
"canvas": "^2.11.2"
1616
},
1717
"devDependencies": {

‎tests/rollup.config.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ const
2020
} = namedBuildConfigs,
2121
ZBAR_WASM_PKG_NAME = '@undecaf/zbar-wasm',
2222
// For production, set
23-
// ZBAR_WASM_REPOSITORY = `https://cdn.jsdelivr.net/npm/${ZBAR_WASM_PKG_NAME}@0.10.0`,
23+
// ZBAR_WASM_REPOSITORY = `https://cdn.jsdelivr.net/npm/${ZBAR_WASM_PKG_NAME}@0.10.1`,
2424
ZBAR_WASM_REPOSITORY = `http://localhost:${repositoryPort}`,
2525
ZBAR_WASM = `node_modules/${ZBAR_WASM_PKG_NAME}/dist/zbar.wasm`;
2626

‎tests/webpack.config.cjs‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ module.exports = async () => {
2020
} = namedBuildConfigs,
2121
ZBAR_WASM_PKG_NAME = '@undecaf/zbar-wasm',
2222
// For production, set
23-
// ZBAR_WASM_REPOSITORY = `https://cdn.jsdelivr.net/npm/${ZBAR_WASM_PKG_NAME}@0.10.0`,
23+
// ZBAR_WASM_REPOSITORY = `https://cdn.jsdelivr.net/npm/${ZBAR_WASM_PKG_NAME}@0.10.1`,
2424
ZBAR_WASM_REPOSITORY = `http://localhost:${repositoryPort}`,
2525
ZBAR_WASM = `node_modules/${ZBAR_WASM_PKG_NAME}/dist/zbar.wasm`;
2626

@@ -227,7 +227,7 @@ module.exports = async () => {
227227
},
228228

229229
// Browser ES module with zbar.wasm bundled
230-
// TODO Avoid emitting @undecaf/zbar_wasm/index.js unnecessarily
230+
// TODO Avoid emitting @undecaf/zbar_wasm/index.js unnecessarily (never loaded by the browser)
231231
{
232232
experiments: {
233233
outputModule: true,
@@ -276,7 +276,7 @@ module.exports = async () => {
276276
},
277277

278278
// Browser ES module with zbar.wasm inlined
279-
// TODO Avoid emitting @undecaf/zbar_wasm/index.js unnecessarily
279+
// TODO Avoid emitting @undecaf/zbar_wasm/index.js unnecessarily (never loaded by the browser)
280280
{
281281
entry: webpackBrowserEsmInlined.entryFile,
282282
externals: {
@@ -370,7 +370,7 @@ module.exports = async () => {
370370
},
371371

372372
// Browser script with zbar.wasm inlined
373-
// TODO Avoid emitting @undecaf/zbar_wasm/index.js unnecessarily
373+
// TODO Avoid emitting @undecaf/zbar_wasm/index.js unnecessarily (never loaded by the browser)
374374
{
375375
entry: webpackBrowserScriptInlined.entryFile,
376376
externals: {

0 commit comments

Comments
 (0)