From 1120dfe3f2d5732eb2eda0996726efd33554e42c Mon Sep 17 00:00:00 2001 From: Chris Knight Date: Wed, 10 Jun 2020 18:43:44 +0100 Subject: doc: improve linking to external code docs (#6158) --- docs/linking_to_external_code/import_maps.md | 21 ++++---- .../linking_to_external_code/integrity_checking.md | 56 +++++++++++++++++++++- docs/linking_to_external_code/reloading_modules.md | 24 +++++++--- 3 files changed, 82 insertions(+), 19 deletions(-) (limited to 'docs/linking_to_external_code') diff --git a/docs/linking_to_external_code/import_maps.md b/docs/linking_to_external_code/import_maps.md index fe3a40cd2..8ed9ef891 100644 --- a/docs/linking_to_external_code/import_maps.md +++ b/docs/linking_to_external_code/import_maps.md @@ -16,27 +16,26 @@ Current limitations: Example: -```js -// import_map.json +**import_map.json** +```js { "imports": { - "http/": "https://deno.land/std/http/" + "fmt/": "https://deno.land/std@0.55.0/fmt/" } } ``` -```ts -// hello_server.ts +**color.ts** -import { serve } from "http/server.ts"; +```ts +import { red } from "fmt/colors.ts"; -const body = new TextEncoder().encode("Hello World\n"); -for await (const req of serve(":8000")) { - req.respond({ body }); -} +console.log(red("hello world")); ``` +Then: + ```shell -$ deno run --allow-net --importmap=import_map.json --unstable hello_server.ts +$ deno run --importmap=import-map.json --unstable color.ts ``` diff --git a/docs/linking_to_external_code/integrity_checking.md b/docs/linking_to_external_code/integrity_checking.md index 91d595cda..df0774865 100644 --- a/docs/linking_to_external_code/integrity_checking.md +++ b/docs/linking_to_external_code/integrity_checking.md @@ -1,16 +1,48 @@ ## Integrity checking & lock files +### Introduction + +Let's say your module depends on remote module `https://some.url/a.ts`. When you +compile your module for the first time `a.ts` is retrieved, compiled and cached. +It will remain this way until you run your module on a new machine (say in +production) or reload the cache (through `deno cache --reload` for example). But +what happens if the content in the remote url `https://some.url/a.ts` is +changed? This could lead to your production module running with different +dependency code than your local module. Deno's solution to avoid this is to use +integrity checking and lock files. + +### Caching and lock files + Deno can store and check subresource integrity for modules using a small JSON file. Use the `--lock=lock.json` to enable and specify lock file checking. To -update or create a lock use `--lock=lock.json --lock-write`. +update or create a lock use `--lock=lock.json --lock-write`. The +`--lock=lock.json` tells Deno what the lock file to use is, while the +`--lock-write` is used to output dependency hashes to the lock file +(`--lock-write` must be used in conjunction with `--lock`). + +A `lock.json` might look like this, storing a hash of the file against the +dependency: + +```json +{ + "https://deno.land/std@v0.50.0/textproto/mod.ts": "3118d7a42c03c242c5a49c2ad91c8396110e14acca1324e7aaefd31a999b71a4", + "https://deno.land/std@v0.50.0/io/util.ts": "ae133d310a0fdcf298cea7bc09a599c49acb616d34e148e263bcb02976f80dee", + "https://deno.land/std@v0.50.0/async/delay.ts": "35957d585a6e3dd87706858fb1d6b551cb278271b03f52c5a2cb70e65e00c26a", + ... +} +``` A typical workflow will look like this: +**src/deps.ts** + ```ts // Add a new dependency to "src/deps.ts", used somewhere else. export { xyz } from "https://unpkg.com/xyz-lib@v0.9.0/lib.ts"; ``` +Then: + ```shell # Create/update the lock file "lock.json". deno cache --lock=lock.json --lock-write src/deps.ts @@ -26,8 +58,28 @@ Collaborator on another machine -- in a freshly cloned project tree: ```shell # Download the project's dependencies into the machine's cache, integrity # checking each resource. -deno cache -r --lock=lock.json src/deps.ts +deno cache --reload --lock=lock.json src/deps.ts # Done! You can proceed safely. deno test --allow-read src ``` + +### Runtime verification + +Like caching above, you can also use the `--lock=lock.json` option during use of +the `deno run` sub command, validating the integrity of any locked modules +during the run. Remember that this only validates against dependencies +previously added to the `lock.json` file. New dependencies will be cached but +not validated. + +You can take this a step further as well by using the `--cached-only` flag to +require that remote dependencies are already cached. + +```shell +deno run --lock=lock.json --cached-only mod.ts +``` + +This will fail if there are any dependencies in the dependency tree for mod.ts +which are not yet cached. + + diff --git a/docs/linking_to_external_code/reloading_modules.md b/docs/linking_to_external_code/reloading_modules.md index 94b87b711..01300a5c3 100644 --- a/docs/linking_to_external_code/reloading_modules.md +++ b/docs/linking_to_external_code/reloading_modules.md @@ -1,22 +1,34 @@ ## Reloading modules -You can invalidate your local `DENO_DIR` cache using the `--reload` flag. It's +By default, a module in the cache will be reused without fetching or +re-compiling it. Sometimes this is not desirable and you can force deno to +refetch and recompile modules into the cache. You can invalidate your local +`DENO_DIR` cache using the `--reload` flag of the `deno cache` subcommand. It's usage is described below: -To reload everything +### To reload everything -`--reload` +```ts +deno cache --reload my_module.ts + +``` + +### To reload specific modules Sometimes we want to upgrade only some modules. You can control it by passing an argument to a `--reload` flag. -To reload all standard modules +To reload all v0.55.0 standard modules -`--reload=https://deno.land/std` +```ts +deno cache --reload=https://deno.land/std@v0.55.0 my_module.ts +``` To reload specific modules (in this example - colors and file system copy) use a comma to separate URLs -`--reload=https://deno.land/std/fs/copy.ts,https://deno.land/std/fmt/colors.ts` +```ts +deno cache --reload=https://deno.land/std/fs/copy.ts,https://deno.land/std/fmt/colors.ts my_module.ts +``` -- cgit v1.2.3