Skip to content

Commit 14ca5bd

Browse files
MaciejG604tgodzik
MaciejG604
and
tgodzik
authored
Add docs for offline mode (#2475)
* Add docs for offline mode * Apply suggestions from code review Co-authored-by: Tomasz Godzik <[email protected]> * Explain scala version validation, add manual copying guide --------- Co-authored-by: Tomasz Godzik <[email protected]>
1 parent 7376b2f commit 14ca5bd

File tree

1 file changed

+173
-0
lines changed

1 file changed

+173
-0
lines changed

‎website/docs/guides/offline.md

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
title: Offline mode ⚡️
3+
sidebar_position: 51
4+
---
5+
6+
:::caution
7+
Offline mode is an experimental feature.
8+
9+
Please bear in mind that non-ideal user experience should be expected.
10+
If you encounter any bugs or have feedback to share, make sure to reach out to the maintenance team
11+
on [GitHub](https://github.com/VirtusLab/scala-cli).
12+
:::
13+
14+
The offline mode for Scala CLI was introduced to be used in two situations:
15+
- you want to have more control over the artifacts being downloaded
16+
- your development environment has restricted access to the Internet or certain web domains
17+
18+
In this mode Scala CLI will only use local artifacts cached by coursier. Any attempts to download artifacts will fail unless they're available locally in cache or there is a known fallback.
19+
This applies to everything that Scala CLI normally manages behind the scenes:
20+
- Scala language and compiler artifacts
21+
- JVM artifacts
22+
- Bloop artifacts
23+
- dependency artifacts
24+
25+
## How to use the offline mode
26+
27+
To enable offline mode pass the `--offline` flag to Scala CLI, e.g.:
28+
29+
```bash ignore
30+
scala-cli run Main.scala --offline
31+
```
32+
33+
It is also possible to use the `COURSIER_MODE` environment variable or `coursier.mode` java property.
34+
```bash ignore
35+
export COURSIER_MODE=offline
36+
```
37+
or
38+
```bash ignore
39+
scala-cli -Dcoursier.mode=offline run Main.scala
40+
```
41+
42+
## Changes in behaviour
43+
44+
### Scala artifacts
45+
In offline mode Scala CLI will not perform any validation of the Scala version specified in the project, it will not be checked if such a version has been released.
46+
47+
### JVM artifacts
48+
System JVM will be used or it will be fetched from local cache.
49+
If a different JVM version than the system one is required, it is best to export it to the `JAVA_HOME` environment variable.
50+
It is important to know, that currently if a version is specified with `--jvm` or `using jvm` Scala CLI will ignore the system JVM and try to fetch via coursier.
51+
52+
To start the Bloop server a JVM with version above 17 is required, if it can't be found compilation will fall back to using `scalac` instead.
53+
54+
### Bloop artifacts
55+
If no artifacts for Bloop are available compilation falls back to using `scalac` instead.
56+
57+
### Dependency artifacts
58+
Any attempt to download a dependency will fail, so it is required to have all the dependencies cached locally before compiling.
59+
60+
Dependencies that reside in local repositories like `~/.ivy2/local` will be resolved as usual.
61+
62+
## Setting up the environment
63+
64+
The easiest way to set up the environment is to use [Coursier](https://get-coursier.io).
65+
66+
Installing scala artifacts:
67+
```bash ignore
68+
cs install scala:3.3.0 scalac:3.3.0
69+
```
70+
71+
Installing a JVM:
72+
```bash ignore
73+
cs java --jvm 17
74+
```
75+
76+
Using the two commands above is already enough for running and compiling code using `scalac`.
77+
For fetching code dependencies run:
78+
```bash ignore
79+
cs fetch com.lihaoyi::os-lib::0.9.1
80+
```
81+
Note that the dependency format is the same as for `--dep` and `using dep`. More information about it [here](./dependencies.md).
82+
83+
If you want to use Bloop, you can get it with:
84+
```bash ignore
85+
cs fetch io.github.alexarchambault.bleep:bloop-frontend_2.12:1.5.11-sc-2
86+
```
87+
Note that Scala CLI uses a custom fork of Bloop, so simple `cs install bloop` won't work.
88+
89+
### Setting up the environment manually
90+
91+
It is possible to copy the Scala language artifacts and dependencies to the local Coursier's cache manually.
92+
This can be done by creating a directory structure like this:
93+
```text
94+
COURSIER_CACHE_PATH
95+
└── https
96+
└── repo1.maven.org
97+
└── maven2
98+
└── org
99+
└── scala-lang
100+
└── scala-compiler
101+
└── 2.13.12
102+
├── scala-compiler-2.13.12-sources.jar (OPTIONAL)
103+
├── scala-compiler-2.13.12.jar
104+
└── scala-compiler-2.13.12.pom
105+
```
106+
Path on MacOs `~/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/org/scala-lang/scala-compiler/2.13.12`
107+
108+
Same for a library:
109+
```text
110+
COURSIER_CACHE_PATH
111+
└── https
112+
└── repo1.maven.org
113+
└── maven2
114+
└── com
115+
└── lihaoyi
116+
└── os-lib_3
117+
└── 0.9.1
118+
├── os-lib_3-0.9.1-sources.jar (OPTIONAL)
119+
├── os-lib_3-0.9.1.jar
120+
└── os-lib_3-0.9.1.pom
121+
```
122+
Path on MacOS `~/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/com/lihaoyi/os-lib_3/0.9.1`
123+
124+
The first segments after the `v1` directory are the address of the repository from which the artifact was downloaded.
125+
This part can effectively be `https/repo1.maven.org/maven2` since maven central is the default repository to use.
126+
The rest of the path is the artifact's organization (split by the '.' character) and version.
127+
128+
## Testing offline mode
129+
130+
To perform a test of environment setup for offline mode, it may be useful to create a clean cache directory for coursier.
131+
To do so, run:
132+
```bash ignore
133+
mkdir test-coursier-cache
134+
export COURSIER_CACHE=`pwd`/test-coursier-cache
135+
```
136+
And proceed with setting up the environment as described above:
137+
```bash ignore
138+
# Should fail with:
139+
# [error] Error downloading org.scala-lang:scala3-compiler_3:3.3.0
140+
scala-cli run Main.scala --jvm 11 --offline
141+
cs install scala:3.3.0 scalac:3.3.0
142+
143+
# Could fail with:
144+
# Error while getting https://github.com/coursier/jvm-index/raw/master/index.json
145+
# But may also pass on MacOS ('/usr/libexec/java_home -v' is tried)
146+
# or if a JVM is cached in coursier's archive cache (this cache's location can't be overridden), you may want to clear it, see section below
147+
scala-cli run Main.scala --jvm 11 --offline
148+
cs java --jvm 11
149+
150+
# Should pass with a warning:
151+
# [warn] Offline mode is ON and Bloop could not be fetched from the local cache, using scalac as fallback
152+
scala-cli run Main.scala --jvm 11 --offline
153+
cs fetch io.github.alexarchambault.bleep:bloop-frontend_2.12:1.5.11-sc-2
154+
155+
# Should pass with a warning:
156+
# [warn] Offline mode is ON and a JVM for Bloop could not be fetched from the local cache, using scalac as fallback
157+
scala-cli run Main.scala --jvm 11 --offline
158+
cs java 17
159+
160+
Should pass with no warnings
161+
scala-cli run Main.scala --jvm 11 --offline
162+
```
163+
164+
## Clearing coursier's caches
165+
Citing [Coursier's docs](https://get-coursier.io/docs/cache#default-location): <br/>
166+
On a system where only recent versions of coursier were ever run (>= 1.0.0-RC12-1, released on the 2017/10/31), the default cache location is platform-dependent:
167+
- on Linux, `~/.cache/coursier/v1`. This also applies to Linux-based CI environments, and FreeBSD too
168+
- on OS X, `~/Library/Caches/Coursier/v1`
169+
- on Windows, `%LOCALAPPDATA%\Coursier\Cache\v1`, which, for user Alex, typically corresponds to `C:\Users\Alex\AppData\Local\Coursier\Cache\v1`
170+
171+
So clearing the cache is just a matter of removing the `v1` directory corresponding to the platform you're on.
172+
However, Coursier does use a second archive cache, which should be located in the same place as the `v1` directory, e.g. `~/.cache/coursier/arc`,
173+
this cache's location can't be overridden, so it may be necessary to clear it for proper testing.

0 commit comments

Comments
 (0)