virtualbox/README.build

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.