Building "bleeding edge" from GIT for users

    As new upstream versions of the proprietary driver are released, upload
    might not happen immediately. This might be for various reasons, including
    waiting for new binary packages to clear the NEW queue.
    Users wishing to try to build new version locally can follow the
    instructions on the Debian wiki:

    https://wiki.debian.org/NvidiaGraphicsDrivers#Building_newer_releases_from_GIT

    WARNING: these will most likely be work in progress, and the final upload
    may be different and may not support clean upgrades from/to the versions
    uploaded in the archive.


The branch structure in the GIT repository

    The following branches exist in the git repository:

    branch                    upload to           merge into
                              (compatible with)   (reintegrate into)

    {71,96,173}xx/*     EoL
    304                 EoL   wheezy              304-jessie
    304-jessie          EoL   (jessie)            304-stretch, 340, 304xx/jessie
    304-stretch         EoL   (stretch)           340-stretch, 304xx/master
    304xx/jessie        EoL   jessie              304xx/master
    304xx/master        EoL   stretch,sid
    340                 EoL   jessie              340-stretch
    340-stretch         EoL   (stretch,sid)       390, 340xx/master
    340xx/master        EoL   stretch,buster,sid
    390                       stretch             390-buster
    390-buster                (buster)            master, 390xx/master
    390xx/master              buster,sid
    418                       (sid)               418-tesla
    418-tesla                 (sid)               tesla-418/master
    tesla-418/master          sid
    440                       (sid)               440-tesla
    440-tesla                 (sid)               tesla-440/master
    tesla-440/master          sid
    master                    sid                 YYY
    YYY                       experimental        ZZZ, (master)
    ZZZ                       experimental        (master)
    *-backports               *-backports
    ABCxx/*-backports         *-backports
    tesla-ABC/*-backports     *-backports

    New upstream releases (XXX.yy) are always imported into the XXX branch.
    If this branch does not yet exist, fork it from ZZZ or master (but do
    not adjust the debian-branch in gbp.conf for non-persistent branches).

    Try to avoid creating XXX-$testing (and ABCxx/$testing) branches as
    long as possible by postponing stable-incompatible changes in branches
    currently used used for both stable and sid.

    Minor updates, fixes and features should always go to the oldest branch
    where they are applicable, i.e. 390-stretch (or 390) in most cases.

 -- Andreas Beckmann <anbe@debian.org>  Sun, 26 Jan 2020 22:49:17 +0100


Importing a New Upstream Release

    The orig tarballs for nvidia-graphics-drivers are split by
    architecture. The *.orig.tar.gz file contains just an empty directory
    and the *.orig-<arch>.tar.gz files contain the upstream .run file for
    the corresponding architecture.
    Everything else comes from the GIT repository for the package.

    Use the following steps to update to a new upstream release:

    * Check for a new version

          uscan --report

    * Create a changelog entry for the new version

          debchange --distribution UNRELEASED --newversion <version>-1

    * Download the driver archives and create new .orig*.tar.gz

          debian/rules get-orig-source

    * Add the new *.orig*.tar.gz to a new <version> subdirectory in the
      git repository ../tarballs-nvidia-graphics-drivers, i.e.
      git@salsa.debian.org:nvidia-team/tarballs-nvidia-graphics-drivers.git


Building and Uploading

    The easiest way to do this is to pick the architecture on which one
    can easily build and test (amd64) and ensure the
    package is working there.  Then, do a final package build for upload.
    Note that you don't need an
    NVIDIA card on the system where you're doing the build, but of course
    ideally you want to test on all architectures before upload.  Most
    problems (at least of the kind that can be fixed in Debian) come from
    building the kernel modules, which you can do without having an NVIDIA
    card.

 -- Russ Allbery <rra@debian.org>, Tue,  6 Apr 2010 23:36:07 -0700


Using the nks-history.git repository for upstreams changelog and the non-blob
parts of the kernel module

    This repository is intended to simplify extracting upstream changelog
    updates.

    To setup an initial clone of this repository run these two commands in
    an empty directory:

      git clone https://salsa.debian.org/nvidia-team/nks-history.git history
      git clone https://salsa.debian.org/nvidia-team/nks-history.git --reference history -b scripts scripts

    To import the changelog and module source of a new release follow
    these instructions:

    * Change to the scripts directory.
    * Edit 'versions'.
    * Run ./00import-history
    * Look at the imported history (in the ../history repository) e.g. using
      gitk. If something was wrong or a parent was missing, edit 'versions'
      and run ./00import-history again. Repeat until you are happy.
    * Commit 'versions' and push both repositories (scripts and history).
    * Update debian/changelog with data from nks-history.

 -- Andreas Beckmann <anbe@debian.org>  Sun, 09 Nov 2014 14:49:10 +0100


Testing kernel module compilation

    The following approach has been useful to test nvidia-kernel-source (or
    a corresponding legacy variant) against a range of kernel headers. The
    dkms packages are less suited for semi-automatic testing.

    Initial setup amd64:
    * setup a minimal sid chroot for the target architecture (debootstrap)
    * setup a schroot configuration for easy usage
    * include all releases to be tested in the sources.list
      (the linux-headers-*-all metapackages from oldstable/stable/backports/
      testing/ sid/experimental/*-backports are co-installable)
    * install as many linux-headers-* (meta-)packages as you want to test

    Initial setup ppc64el:
    * install the package: qemu-user-static (MUST be version >= 1:2.3)
    * cowbuilder yields best results compared to chroot/schroot/pbuilder, for
      detailed instructions see: https://wiki.debian.org/cowbuilder
    * define or export DEBOOTSTRAP="qemu-debootstrap" ARCH="ppc64el" before
      every step

    Testing a new nvidia*-kernel-source package:
    * enter the chroot as root, update it, install new linux-headers-*
    * install the new package to be tested with dpkg
    * run
      sh /usr/share/doc/nvidia-kernel-source/build-module-packages.sh
    * and wait, this will iterate over all available linux-headers
    * should any fail to build, module-assistant will print an error and
      wait for return being pressed before continuing

 -- Andreas Beckmann <anbe@debian.org>  Tue, 04 Aug 2015 11:54:28 +0200


The kernel modules get renamed to allow concurrent installation of the
current and the legacy drivers. Only one module can be loaded at a time.
Only the module filename gets renamed, the internal name is kept unchanged,
otherwise the module seems to get confused. This needs some special care
for unloading it, which is realized via modprobe configuration.

 -- Andreas Beckmann <anbe@debian.org>  Tue, 11 Aug 2015 18:15:47 +0200


Importing a new upstream release that moved support for some legacy cards
to a new legacy driver

    * Import the new upstream (as usual) into a new branch, first targeting
      experimental.
    * Build a list of no longer supported PCI IDs:
        comm -23 ../../trunk/debian/nv-readme.ids debian/nv-readme.ids > unsupported.ids
    * Replace the PCI ID list in debian/nvidia-legacy-check.preinst.
    * Build lists of the no longer supported GPU model and chipset names:
        debian/rules unsupported.names
        sort -k2 unsupported.names > unsupported.names.sorted
        sed 's/.*\[/[/' unsupported.names | sort -u > chips-eol.txt
    * Create an nvidia-driver.NEWS entry about the legacy models.
    * Update debian/control.models to the still supported ones.

 -- Andreas Beckmann <anbe@debian.org>  Tue, 14 Oct 2014 16:11:22 +0200


Forking a new legacy package

    In order to create a new legacy package (e.g. for legacy version 42)
    from this source package, the following changes need to be done:

    * in debian/rules.defs set   NVIDIA_LEGACY = 42

    * in
        - debian/changelog
        - debian/control (Source: and Package: lines)
      change the package name by inserting '-legacy-42xx' into the package
      name after
        - nvidia-glx
        - libgl1-nvidia
        - nvidia-kernel
        - nvidia-graphics-drivers

    * remove all packages that should no longer be built from debian/control

 -- Andreas Beckmann <debian@abeckmann.de>  Mon, 07 Jun 2010 16:10:09 +0200
