mirror of
https://github.com/roc-lang/roc.git
synced 2025-10-03 16:44:33 +00:00
small edits
Signed-off-by: Anton-4 <17049058+Anton-4@users.noreply.github.com>
This commit is contained in:
parent
8b96f6aa5c
commit
37acc3a847
1 changed files with 10 additions and 8 deletions
|
@ -1415,7 +1415,7 @@ You can find documentation for the `Stdout.line` function in the [Stdout](https:
|
||||||
|
|
||||||
### [Package Modules](#interface-modules) {#interface-modules}
|
### [Package Modules](#interface-modules) {#interface-modules}
|
||||||
|
|
||||||
Package modules enable Roc code to be shared across multiple applications and platforms. This is achieved by organizing code into different Interface modules and then including these in the `exposes` field of the package file structure, `package "name" exposes [] packages {}`. The modules that are listed in the `exposes` field are then exported and available for use by applications or packages. Other internal modules that are not listed will be unavailable for use outside of the package.
|
Package modules enable Roc code to be easily re-used and shared. This is achieved by organizing code into different Interface modules and then including these in the `exposes` field of the package file structure, `package "name" exposes [ MyInterface ] packages {}`. The modules that are listed in the `exposes` field are then available for use in applications, platforms, or other packages. Internal modules that are not listed will be unavailable for use outside of the package.
|
||||||
|
|
||||||
See [Parser Package](https://github.com/roc-lang/roc/tree/main/examples/parser/package) for an example.
|
See [Parser Package](https://github.com/roc-lang/roc/tree/main/examples/parser/package) for an example.
|
||||||
|
|
||||||
|
@ -1423,19 +1423,21 @@ Package documentation can be generated using the Roc cli with `roc docs /package
|
||||||
|
|
||||||
Build a package for distribution with `roc build --bundle .tar.br /package/main.roc`. This will create a single tarball that can then be easily shared online using a URL.
|
Build a package for distribution with `roc build --bundle .tar.br /package/main.roc`. This will create a single tarball that can then be easily shared online using a URL.
|
||||||
|
|
||||||
You can import a package that is available either locally, or from a URL into a Roc application or platform. This is achieved by specifying the package in the `packages` section of the application or platform file structure. For example, `packages { .., parser: "<package URL>" }` is an example that imports a parser module from a package URL.
|
You can import a package that is available either locally, or from a URL into a Roc application or platform. This is achieved by specifying the package in the `packages` section of the application or platform file structure. For example, `packages { .., parser: "<package URL>" }` is an example that imports a parser module from a URL.
|
||||||
|
|
||||||
How does the Roc cli import and download a package from a URL?
|
How does the Roc cli import and download a package from a URL?
|
||||||
|
|
||||||
1. First check to see whether the relevant folder already exists in the local filesystem and if not, create it. If there is a package already downloaded then there is no need to download or extract anything. Packages are cached in a temporary directory, typically `~/.cache/roc` on UNIX, and `%APPDATA%\\Roc` on Windows.
|
1. First it checks to see whether the relevant folder already exists in the local filesystem and if not, creates it. If there is a package already downloaded then there is no need to download or extract anything. Packages are cached in a directory, typically `~/.cache/roc` on UNIX, and `%APPDATA%\\Roc` on Windows.
|
||||||
2. Download the file at that URL into a tempdir and verify that the hash of the file matches the hash at the end of the URL.
|
2. It then downloads the file at that URL and verifies that the hash of the file matches the hash at the end of the URL.
|
||||||
3. If the hash of the file matches the hash in the URL, then decompress and extract its contents into the cache folder so that it can be used.
|
3. If the hash of the file matches the hash in the URL, then decompress and extract its contents into the cache folder so that it can be used.
|
||||||
|
|
||||||
Why is a Roc URL package such a long URL? This solves a number of problems that some package systems which permit downloads from arbitrary URLs have. These are summarized as follows;
|
Why is a Roc package URL so long?
|
||||||
|
|
||||||
1. Reliability - the contents of the URL can change at any time, so you might think you're getting one version today, but then the author might publish a new version tomorrow at the same URL - and now some of your teammates are working with different versions of the code, and you don't even realize it until you start getting bizarrely different results.
|
Including the hash solves a number of problems:
|
||||||
2. Cacheability - because of #1, it's hard to know whether it's safe to cache the file or else go back to the server for a potentially fresh copy; at a minimum, you probably want to ping the server to check ETags etc. This hurts compile times, because you have to wait for all those server responses.
|
|
||||||
3. Security - suppose the package author isn't malicious, but they host their package on a URL with a domain that they eventually forget about and let expire. A malicious actor realizes people are still out there using that URL (perhaps a popular tutorial links to it, so beginners are downloading it fresh all the time), so they register the expired domain and host a malicious version of the package that's API-compatible but does bad things. This is trivial if the package is a platform, since platforms can (necessarily) execute arbitrary C code.
|
1. The package at the URL can not suddenly change and cause different behavior.
|
||||||
|
2. Because of 1. there is no need to check the URL on every compilation to see if we have the latest version.
|
||||||
|
3. If the domain of the URL expires, a malicious actor can change the package but the hash will not match so the roc cli will reject it.
|
||||||
|
|
||||||
### [Interface Modules](#interface-modules) {#interface-modules}
|
### [Interface Modules](#interface-modules) {#interface-modules}
|
||||||
|
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue