This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Instructions for building the VirtualBox project
Although it is possible to modify a project at the openSUSE Build System (OBS),
I have found it to be more convenient to use the various osc commands to create a
local copy, edit it on my own computer to fix any problems, and then push the result
to OBS.
You will need a login account at OBS. This account is also used to login at openSUSE's
bugzilla, etc. Those credentials are also used by osc whose package must also be
installed.
A. Create a new sub-project:
1. Branch the package:
The sources for Tumbleweed and the Leap releases have been merges, thus
development work can be concentrates on TW. To branch VB for Tumbleweed,
osc branch Virtualization virtualbox
2. Checkout the package using the "osc co" command listed
B. For the first time, test Build the project:
1. Use "osc build" to build. This step is rather compute intensive and
takes about an hour on my Toshiba laptop with a dual-core Intel Core i7 CPU
with hyper-threading, 12 GB RAM, and an SSD. This build will create all the
VirtualBox packages except the kernel modules. To build them use "osc build -M kmp",
which takes a lot less time. The split was made to reduce the load on OBS.
Now, a kernel change only requires rebuild of the modules, not the entire package.
2. The build results are stored in the /var/tmp/build-root tree. These files
can occupy a lot of disc space, particularly when one builds several flavors.
To keep from running out of space on the / partition, I mount /var/tmp on
a separate partition. In general, about 25 GB is required for each flavor,
thus the disk usabe can approach 100 GB. If you have plenty of headroom in /,
you can skip this separate partition.
3. Special flavors:
When a new kernel is released, there may be several API changes that affect
builds of the kernel modules used by VirtualBox. In Factory, the project that
contains the latest kernels is "Kernel-HEAD-standard". To run a test build with
this kernel, use the command " osc build --alternative-project Kernel:HEAD standard".
Note: The syntax of this step has changed throughout the years. If it fails, ask
how to do it on the openSUSE Factory mailing list at opensuse-factory@opensuse.org.
When switching between kernel projects, use of the "--clean" switch is advised,
otherwise strange "missing library" messages will result.
4. On occasion, there may be breakage in the build when there is an update of
python or Qt. Use the "--alternative-project=<xxx>" switch to force usage of
the revised component. You will need to ask at factory@lists.opensuse.org to
get the proper profect name.
C. Steps to take with a new release:
1. When Oracle releases a new version, you will need to download the new tarball
from https://download.virtualbox.org/virtualbox/. While downloading the file, I
also get the new UserManual.pdf. I use the wget utility, but the browser could
be used.
2. openSUSE makes some changes to the tarballi, which are done with the command
bash ./virtualbox-patch-source.sh <name of tarball just downloaded>
This script unpacks the tar file, removes Windows and Mac host code from the file,
and recreates the tar file with "patched" in its name. Any further modifications
are made by patches that are applied during the build process. Do NOT make any
further changes to the tar file.
3. Edit the "Version" line near the start of virtualbox.spec to select the new version.
4. Use "osc rm <old_tarball-name>" and "osc add <new_tarball_name>" to get the
new file into osc. The local build will work without these changes, but the remote
operations with OBS will fail.
5. VirtualBox at openSUSE is a multi-build package consisting of virtualbox-kmp and
the rest of virtualbox. The former builds in about 20% of the time needed for the
latter, thus it is best to start with the kmp part.
6. The usual problems are as follows:
a. Fixing for kernel API changes are incorporated in a new release, thus our patch
is obsolete.
b. Oracle has revised their code such that one of the patches needed by openSUSE
fails to apply.
c. There are kernel API changes that break the building of the kmp part of VB.
5. When fixing kernel API changes, keep in mind that Oracle will be 2-3 months behind
your needs; however, they will eventually include the necessary changes in their
distribution. If you find something that you do not know how to fix, you could file
a bug tracker at https://www.virtualbox.org/wiki/Bugtracker. Note that previous
reports have gotten the response "We do not support kernel X.Y" - a really helpful
response. To be able to back out your changes, create a new patch file for the
updates. An OBS or osc build will unpack the "patched" tarball and apply the patches.
To help in the creation of such patches, it is my practice to untar the tarball and
use quilt to create the necessary patch, refresh it, and then copy it back into the
main directory. At that point it can be added into the spec file. The utility
wiggle is useful in fixing patches that will not apply.
6. Once the kmp modules, and the main part of VirtualBox are building correctly with
osc, use 'osc status' to indicate the file changes. Anything with a "?" as its status
is a new file that needs to be resolved. If these files are not added to the project,
they will not be uploaded to OBS. You should also remove any files made obsolete
because Oracle caught up with kernel API changes. At this point, the new release
should be tested by adding the directory
/var/tmp/build-root/.../home/abuild/rpmbuild/RPMS/x86_64
to the list of repositories, and updating virtualbox from that new repository. These
packages will not be signed, thus you will get a warning that can be ignored. Be sure
to install virtualbox-host-source, as well as kernel-default-devel and kernel-devel
for the kernel you are running. After loading the updated packages, then run
'sudo /lib/sbin/vboxconfig' to build and install the kernel modules.
7. The new code can now be tested. Usually, the tests will not show any problems;
however, there was a version where Windows 7 failed to boot because of a virtual
BIOS change. With kernel 5.18, there was a major bug where the FPU was not being
saved. The symptoms ranged from application crashes in a Linux VM to a full virtual
machine crash in a Windows 10 VM. The patch for this problem was provided by Oracle,
only a few days before kernel 5.18.1 was released and added to Tumbleweed. Obviously,
both Windows and Linux systems should be tested to ensure that screen resizing,
bidirectional clipboard, and shared folders work with no crashes.
8. Once the new release is tested and 'osc status' is clean, it is time to update the
changes file using the 'osc vc' command. I copy and paste the changes listed in
the Oracle release notes to the new entry and add references to any bugzilla entries.
In this section, it is essential that you list files that are deleted or added. It is
not necessary to mention the tarball change - it is implied.
9. Now it is time to send the new material to OBS using the 'osc ci' command. The
material in the new section usually appears as the commit message. If not, copy it
from the .changes file. Committing new material will trigger builds at OBS. The
status of them can be seen with the 'osc r' command. Once the builds are successful,
they should be submitted using the 'osc sr' for Tumbleweed. One peculiarity of the
factory releases is that they require a review, even for your own changes. A few
minutes after an ‘osc sr’ command, you will need to log into OBS and check your
tasks for “Outgoing Requests”. From there, you will be able to submit a review.
10. After VirtualBox is completed for Tumbleweed, and building OK on the various Leap
versions at OBS, you can branch the various Leap versions with the command
osc branch openSUSE:Leap:15.X:Update virtualbox
It is not necessary to check out the code as creating the directory that will
be used. If it already exists on your system, delete all files in that directory.
Then copy all the files from the Tumbleweed source into the Leap directory. To
syncronize your system wuth OBS, do an "osc update". At this point, you will
need to repeat the "osc rm" and "osc add" steps to update the version of the
tarball. After that, make sure that "osc status" is clean. At that point, update
the package at OBS with "osc ci". When "osc r" shows that the build has completed,
use "osc mr" to submit it to the project. For the update projects, no review by
the maintainer is requied.
11. When a new Leap release is in a pre-release state, updated VB releases can be
sent to that project from OBS.