You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
📚 Docs: update build-vagrant.md for Ubuntu 24.04 and current workflow
Update the `build-vagrant.md` documentation to reflect the current build system and fix
outdated or incorrect information. Split VM creation and Ansible provisioning into two
explicit steps, clarify that `vagrant-vbguest` is optional troubleshooting tool, remove
redundant commands now handled automatically by `tox`, and add a simply not on the
time required.
Install [tox](https://tox.readthedocs.io/) and the `vagrant-vbguest` plugin:
44
+
Install [tox](https://tox.readthedocs.io/):
63
45
64
46
```bash
65
47
pip install tox
66
-
# improves interface
67
-
vagrant plugin install vagrant-vbguest
68
48
```
69
-
:::{tip}
70
-
For those using [Conda](https://docs.conda.io/), it is recommended to also install [tox-conda](https://github.com/tox-dev/tox-conda):
71
-
72
-
```bash
73
-
pip install tox-conda
74
-
```
75
-
76
-
:::
77
49
78
50
## Create the Virtual Machine
79
51
80
-
:::{seealso}
81
-
If you would like to [customise](customize.md) any aspects of the VM, now would be a good time to do so.
82
-
:::
83
-
84
-
85
-
Use [tox](https://tox.readthedocs.io/) to set up the Python environment and run the build steps.
52
+
We use [tox](https://tox.readthedocs.io/) to set up the Python environment and run the build steps.
86
53
87
54
```bash
88
-
tox -a -v# shows available automations
89
-
tox -e vagrant
55
+
tox -e vagrant# create and start the VM
56
+
tox -e ansible # provision the VM with Ansible
90
57
```
91
-
This will call `vagrant up`, to initialise the VM, which then calls `ansible-playbook playbook-build.yml`, to configure the VM and build the required software on it.
92
58
93
-
:::{tip}
94
-
If you get an error during the installation of the VirtualBox Guest Additions, you may need to perform additional steps (see [issue #60](https://github.com/marvel-nccr/quantum-mobile/issues/60)).
95
-
:::
96
-
:::{tip}
97
-
Building the Desktop Edition is tested on GitHub Actions on every commit to the repository.
98
-
For the tested steps see the `.github/workflows/build.yml` file.
99
-
:::
59
+
This will:
60
+
1.`tox -e vagrant`: Call `vagrant up` to create and start the VM
61
+
2.`tox -e ansible`: Generate the SSH configuration file (`vagrant-ssh`) and call `ansible-playbook playbook-build.yml` to provision the VM and build the required software on it
62
+
63
+
You can see all available `tox` environments with:
100
64
65
+
```bash
66
+
tox -a -v # shows available automations
67
+
```
101
68
102
69
### Continuing a failed build
103
70
104
71
If the build fails or is interrupted at any step (for example a failed download, due to a bad connection),
105
72
you can continue the build with:
106
73
107
74
```bash
108
-
# output the vagrant box connection details
109
-
vagrant ssh-config > vagrant-ssh
110
75
tox -e ansible
111
76
```
112
77
113
78
The ansible automation steps are generally idempotent, meaning that if they have been previously run successfully, then they will be skipped in any subsequent runs.
114
79
80
+
:::{note}
81
+
You don't need to manually run `vagrant ssh-config > vagrant-ssh` - `tox -e ansible` does this automatically.
82
+
:::
83
+
115
84
### Running only selected steps
116
85
117
86
All steps of the ansible build process are "tagged", which allows you to select to run only certain steps, or skip others.
@@ -156,10 +119,38 @@ This will compact the hard disk of the virtual machine and export the image and
156
119
The `validate` tag checks that the repositories git tag is the same as the `vm_version` specified in `inventory.yml`, and is only needed for new releases by Quantum Mobile maintainers.
157
120
:::
158
121
159
-
## Other Useful commands
122
+
###Other Useful commands
160
123
161
124
-`vagrant reload`: restart machine
162
125
-`vagrant halt`: stop machine
163
126
164
127
Vagrant keeps information on how to connect in a folder called `.vagrant`.
165
128
If you would like to create a new machine, `vagrant destroy` will remove the `.vagrant` folder and allow you to create a new VM (note: you may want to keep a copy in case you want to reconnect later).
129
+
130
+
## Troubleshooting
131
+
132
+
### VirtualBox Guest Additions Issues
133
+
134
+
If you experience issues with shared folders, clipboard sharing, or graphics performance, you may need to manage VirtualBox Guest Additions manually.
135
+
Install the `vagrant-vbguest` plugin:
136
+
137
+
```bash
138
+
vagrant plugin install vagrant-vbguest
139
+
```
140
+
141
+
Then you can:
142
+
143
+
```bash
144
+
# Check Guest Additions status
145
+
vagrant vbguest --status
146
+
147
+
# Manually install/update Guest Additions
148
+
vagrant vbguest --do install
149
+
150
+
# Rebuild Guest Additions
151
+
vagrant vbguest --do rebuild
152
+
```
153
+
154
+
:::{note}
155
+
VirtualBox Guest Additions are tools that run inside the VM to provide features like shared folders, seamless mouse integration, and better graphics. The base Ubuntu box comes with Guest Additions pre-installed, but version mismatches can occur when you upgrade VirtualBox, potentially causing shared folder or clipboard issues. This plugin helps resolve such mismatches.
0 commit comments