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.


Upstream support timeframes

    https://nvidia.custhelp.com/app/answers/detail/a_id/3142
    https://docs.nvidia.com/datacenter/tesla/drivers/
    https://web.archive.org/web/20210522000916/https://docs.nvidia.com/datacenter/tesla/drivers/

    Driver Series       Supported until
    71                          EoL
    96                          EoL
    173                         EoL
    304                 12/2017 EoL
    340                 12/2019 EoL
    390                 12/2022 EoL
    Tesla 410                   EoL
    Tesla 418 (LTSB)    03/2022 EoL
    Tesla 440           11/2020 EoL
    Tesla 450 (LTSB)    07/2023
    Tesla 460 (PB)      01/2022 EoL
    Tesla 470 (LTSB)    07/2024
    Tesla 510 (PB)      01/2023 EoL
    Tesla 515 (PB)      05/2023
    Tesla 525 (PB)      12/2023


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/main
    340xx/main          EoL   stretch,buster,sid
    390                 EoL   stretch             390-buster
    390-buster          EoL   (buster)            418, 390xx/main
    390xx/main          EoL   buster,bullseye,sid
    418                 EoL   buster              418-bullseye
    418-bullseye        EoL   (bullseye)          450, 418-tesla
    418-tesla           EoL   (bullseye)          450-tesla, tesla-418/main
    tesla-418/main      EoL   bullseye,sid        tesla-450/main
    450                       (bullseye)          460, 450-tesla
    450-tesla                 (bullseye)          460-tesla, tesla-450/main
    tesla-450/main            bullseye,sid        tesla-460/main
    460                 EoL   (bullseye)          470, 460-tesla
    460-tesla           EoL   (bullseye)          470-tesla, tesla-460/main
    tesla-460/main      EoL   (bullseye),(sid)    tesla-470/main, tesla-460/transition-470
    tesla-460/transition-470  bullseye,sid
    470                       bullseye            510, 470-tesla
    470-tesla                 (bullseye)          510-tesla, tesla-470/main
    tesla-470/main            bullseye,bookworm,sid tesla-510/main
    510                 EoL   (bookworm),sid      515, 510-tesla
    510-tesla           EoL   (bookworm)          515-tesla, tesla-510/main
    tesla-510/main      EoL   (bookworm),(sid)    tesla/510, tesla-510/transition
    tesla-510/transition      sid
    tesla/510           EoL   (bookworm),sid      tesla/515
    515                       (bookworm),sid      525, 515-tesla
    515-tesla                 (bookworm)          525-tesla, tesla/515
    tesla/515                 (bookworm),sid      tesla/525
    525                       (bookworm),sid      YYY, 525-tesla
    525-tesla                 (bookworm)          ZZZ-tesla, tesla/525
    tesla/525                 (bookworm),sid      tesla/ZZZ
    main                      sid                 YYY
    tesla/main                sid
    YYY                       experimental        ZZZ, (main)
    ZZZ                       experimental        (main)
    ZZZ-tesla                 (experimental)      tesla/ZZZ
    tesla/ZZZ                 experimental        (tesla/main)
    *-backports               *-backports
    ABCxx/*-backports         *-backports
    tesla-ABC/*-backports     *-backports
    tesla/*-backports         *-backports

    New upstream releases (XXX.yy[.zz]) are always imported into the XXX
    branch. If this branch does not yet exist, fork it from ZZZ (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. 340-stretch (or 390) in most cases.

    The following packages have hardcoded lists of alternative dependencies
    that need to be updated whenever the list of supported driver packages
    changes:
     * src:nvidia-persistenced  debian/control
     * src:bumblebee            debian/rules
     * src:primus               debian/rules
     * src:primus-vk            debian/rules
     * src:python-pynvml        debian/rules

 -- Andreas Beckmann <anbe@debian.org>  Mon, 19 Dec 2022 17:16:30 +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

          debian/rules commit-current-tarballs


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
