@@ -14,10 +14,8 @@ Unix/Linux). The installation process will create a new Virtual
14
14
Machine (VM) on your computer and the VM will use the Ubuntu GNU/Linux
15
15
operating system.
16
16
17
- __ Note:__ We only officially support and test development using VirtualBox.
18
- The instructions below are for VirtualBox. While alternatively using
19
- VMWare should work, we have not tested this, and do not provide these
20
- instructions.
17
+ *** NOTE:** We only officially support and test development using VirtualBox for AMD
18
+ and Intel machines and QEMU for M-Series ARM MacOS machines.*
21
19
22
20
---
23
21
@@ -43,24 +41,23 @@ instructions.
43
41
backend, which will be slower and can cause instability in the
44
42
VM.
45
43
46
- ** Note:**
47
- This may stop programs like Docker Desktop and WSL 2 from
44
+ *** NOTE:** This may stop programs like Docker Desktop and WSL 2 from
48
45
working. If these programs are essential to your workflow, consider
49
46
looking up how to add a separate boot entry with "hypervisorlaunchtype"
50
- set to "off" for use with VirtualBox.
47
+ set to "off" for use with VirtualBox.*
51
48
52
- ** Note:**
53
- Installing WSL2 may also reconfigure your OS to use Hyper-V or Windows hypervisor
49
+ *** NOTE:** Installing WSL2 may also reconfigure your OS to use Hyper-V or Windows hypervisor
54
50
platform and prevent VirtualBox from working correctly. It is recommended to not install
55
- or use WSL2 alongside Virtualbox for now.
51
+ or use WSL2 alongside Virtualbox for now.*
56
52
57
- 5 . If you're on M-series macOS , you will be using QEMU with SMB file sharing.
53
+ 5 . If you're on M-series ARM MacOS (e.g., M1, M2, M3) , you will be using QEMU with SMB file sharing.
58
54
To enable this, open ** System Settings** and navigate to ** General > Sharing** .
59
55
Press the (i) button next to ** File Sharing** , and in the popup window
60
56
click "Options...". Then turn on "Share files and folders using SMB" and
61
57
check the box next to your name in the list below.
62
58
63
- 6 . The complete installation process could take an hour or more. Make
59
+ 6 . The complete installation process could take an hour or more and
60
+ will quite possiby fail if paused or interrupted. Make
64
61
sure your internet connection is strong and consistent. You'll
65
62
probably want to plug in your laptop power cord. Check your
66
63
computer settings and make sure the machine does not hibernate or
@@ -110,7 +107,7 @@ instructions.
110
107
3 . Locate ** Virtualization** and enable it. (Some motherboards may call it SVM, AMD-V, VT-x/Vanderpool)
111
108
4 . Be sure to choose ** Hardware Virtualization** in the ** System -> Acceleration**
112
109
settings of the virtual machine you are using.
113
- 5 . ** Note :** If using secure boot, Vagrant may fail to work with VirtualBox.
110
+ 5 . ** NOTE :** If using secure boot, Vagrant may fail to work with VirtualBox.
114
111
You will then either need to disable secure boot from the boot menu/BIOS or
115
112
follow [ these steps] ( https://era86.github.io/2018/01/24/vagrant-virtualbox-secureboot-in-ubuntu-1604.html )
116
113
to self-sign the necessary packages to run Vagrant and VirtualBox.
@@ -122,18 +119,27 @@ instructions.
122
119
123
120
* [ Ruby] ( https://www.ruby-lang.org/en/downloads )
124
121
* [ Git] ( https://git-scm.com/downloads )
125
- * [ VirtualBox] ( https://www.virtualbox.org/wiki/Download_Old_Builds_6_1 ) (or [ QEMU] ( https://www.qemu.org ) instead for M-series macOS)
122
+ * M-SERIES ARM MacOS: [ QEMU] ( https://www.qemu.org )
123
+ * EVERYONE ELSE: [ VirtualBox] ( https://www.virtualbox.org/wiki/Download_Old_Builds_6_1 )
126
124
* [ Vagrant] ( https://www.vagrantup.com )
127
125
128
126
129
127
* ** MacOS**
130
128
You can either go to respective sites and download the necessary binaries or
131
- install [ Homebrew] ( http://brew.sh/ ) , if you don't have it, and then run :
129
+ install [ Homebrew] ( http://brew.sh/ ) , if you don't have it, and then:
132
130
131
+ If you have an M-series ARM Mac, run:
133
132
```
134
133
brew install --cask vagrant
135
- brew install --cask virtualbox # if on Intel chip
136
- brew install qemu && vagrant plugin install vagrant-qemu # if on M-series chip
134
+ brew install qemu
135
+ vagrant plugin install vagrant-qemu
136
+ ```
137
+
138
+ Or if you have an older Intel-based Mac, run:
139
+
140
+ ```
141
+ brew install --cask vagrant
142
+ brew install --cask virtualbox
137
143
```
138
144
139
145
* **Windows**
@@ -174,6 +180,7 @@ instructions.
174
180
sudo dnf install vagrant
175
181
```
176
182
183
+ DELETE
177
184
* **Note:**
178
185
When running vagrant up, use `vagrant up --provider=virtualbox` so it doesn't default to libvirt
179
186
@@ -193,22 +200,23 @@ instructions.
193
200
run `vagrant destroy` before re-running `vagrant up --provider=virtualbox` again.
194
201
195
202
196
- 3 . CLONE THE [SUBMITTY REPOSITORY](https://github.com/Submitty/Submitty)
203
+ 4 . CLONE THE [SUBMITTY REPOSITORY](https://github.com/Submitty/Submitty)
197
204
198
205
* Clone it to a location on your computer (the "host").
199
206
200
207
```
201
208
git clone https://github.com/Submitty/Submitty.git
202
209
```
203
210
204
- **Note :** If you are not currently part of the Submitty organization on GitHub, you may want to
211
+ ***NOTE :** If you are not currently part of the Submitty organization on GitHub, you may want to
205
212
[fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo)
206
- the repo and use the git url from your fork instead, especially if you are looking to contribute.
213
+ the repo and use the git url from your fork instead, especially if you are looking to contribute.*
214
+
207
215
208
- * _OPTIONAL: If you will be developing code in one of the companion
216
+ * **OPTIONAL:** If you will be developing code in one of the companion
209
217
Submitty repositories (e.g., AnalysisTools, Lichen,
210
218
Localization, RainbowGrades, Tutorial), also clone those
211
- repositories to the same directory. For example:_
219
+ repositories to the same directory. For example:
212
220
213
221
```
214
222
home
@@ -223,57 +231,69 @@ instructions.
223
231
└── Tutorial (optional)
224
232
```
225
233
226
- _This host directory structure will be shared / synced between
227
- your host operating system and the Submitty virtual machine._
234
+ *This host directory structure will be shared / synced between
235
+ your host operating system and the Submitty virtual machine.*
228
236
229
237
230
- 4. RUN VAGRANT
231
-
232
- If you have an AMD processor you can choose to download a pre-made
233
- VM that is created weekly OR you can create the VM from scratch
234
- (which will take substantially more time). If you have an ARM chip
235
- (such as Apple M-series), you must create the VM from
236
- scratch.
238
+ 5. RUN VAGRANT
237
239
238
240
239
241
* Navigate into the Submitty repository on your computer in a
240
- shell/terminal. _On Windows, run CMD or PowerShell on administrator mode_.
242
+ shell/terminal. *On Windows, run CMD or PowerShell on administrator mode.*
241
243
242
244
243
245
* **Build pre-packaged VM**
244
246
247
+ *NOTE: The pre-packaged Submitty VM is not (yet)
248
+ available for qemu / M-Series ARM Mac machines.*
249
+
245
250
If you are using VirtualBox as your provider, you will by default
246
- use a pre-packaged Submitty VM. This will have all of Submitty
247
- already setup. Vagrant will build your VM for you.
251
+ use a pre-packaged Submitty VM. This will have all of Submitty
252
+ already setup. This is a recently built machine,
253
+ but it may be slightly older than the current
254
+ [main branch on GitHub](https://github.com/Submitty/Submitty).
255
+
248
256
249
- To create the virtual machine, run:
257
+ To create the virtual machine from the pre-packaged image , run:
250
258
```
251
259
vagrant up --provider=virtualbox
252
260
```
253
- Replace `virtualbox` with `qemu` if on M-series macOS.
254
-
255
- ***Note:** The vagrant up command provisions the virtual machine on the first run.
256
- For subsequent runs, you do not need to append the `--provider` flag as the VM is
257
- already created.*
258
261
259
- If you wish to use a specific version of the pre-packaged Submitty VM, on Linux or Mac type:
262
+ If you wish to use a specific version of the pre-packaged Submitty VM, on Linux type:
260
263
```
261
- PREBUILT_VERSION={version} vagrant up
264
+ PREBUILT_VERSION={version} vagrant up --provider=virtualbox
262
265
```
266
+
263
267
or on Windows, type:
264
268
```
265
- SET PREBUILT_VERSION={version}
266
- vagrant up
269
+ SET PREBUILT_VERSION={version}
270
+ vagrant up --provider=virtualbox
267
271
```
272
+
268
273
*The version must be only the numbers, not including the `v` in front, for example `24.05.00.2405260215` not `v24.05.00.2405260215`*
269
274
270
275
*This process will take 10 minutes to maybe half an hour
271
276
depending on your internet connection speed.*
272
277
273
278
279
+ ***Note:** The vagrant up command provisions the virtual machine on the first run.
280
+ For subsequent runs, you do not need to append the `--provider` flag as the VM is
281
+ already created.*
282
+
283
+
284
+ * **Build (from scratch) using QEMU on an M-Series Arm MacOKS**
285
+
286
+ If you have an M-series ARM MacOS, run:
287
+ ```
288
+ vagrant up --provider=qemu
289
+ ```
290
+
291
+ *As noted above, you do not need to append the `--provider` flag is only necessary on the first run when the VM is created.*
292
+
293
+
274
294
* **Build from scratch**
275
295
276
- If you wish to run `vagrant up` from scratch, on Linux or Mac type:
296
+ If you wish to run `vagrant up` from scratch, on Linux or IntelMac type:
277
297
```
278
298
FROM_SCRATCH=1 vagrant up
279
299
```
@@ -344,7 +364,7 @@ instructions.
344
364
```
345
365
346
366
347
- 5 . AND YOU ARE DONE!
367
+ 7 . AND YOU ARE DONE!
348
368
349
369
When the installation has completed, you should see the message:
350
370
```
0 commit comments