Documentation: properly document installation from source (without binaries)

[s-u]

Since binaries are not provided for current systems (e.g., nVidia only supports CUDA 12.6 on Ubuntu 24.04), it is necessary to build lantern and/or libtorch from sources, but that is entirely undocumented - both on the torch side as well as on the libtorch side. It would be nice to have some documentation for both steps and how to properly integrate them such that torch doesn't try to look for non-existent binaries.

In the hope of being useful, I'm attaching a script with which I managed to get a working torch installation from sources, but I had to reverse-engineer ci scripts both in pytorch and in torch to do that as neither is documented.

## make sure we have CUDA
export PATH=/usr/local/cuda/bin:$PATH
CUDA=$(nvcc --version | sed -nE 's:.*release ([0-9.]+).*:\1:p')
echo Building with CUDA-$CUDA

## get pytorch sources - here we go for the 2.6 release branch
git clone --branch release/2.6 --recursive https://github.com/pytorch/pytorch.git
## create venv for the build tools and dependencies
python3 -m venv pytorch-build-env
. pytorch-build-env/bin/activate
export CMAKE_PREFIX_PATH=$(pwd)/pytorch-build-env

## install dependencies
cd pytorch
pip install cmake ninja
pip install -r requirements.txt
pip install mkl-static mkl-include
make triton

## build pytorch (see docs for more torch options)
export _GLIBCXX_USE_CXX11_ABI=1
python setup.py install

## create libtorch
## this is from .ci/manywheel/build_libtorch.sh
## no idea why this is not part of the pytorch sources ...
mkdir -p libtorch/{lib,bin,include,share}

# Copy over all lib files
cp -rv build/lib/*                libtorch/lib/
cp -rv build/lib*/torch/lib/*     libtorch/lib/

# Copy over all include files
cp -rv build/include/*            libtorch/include/
cp -rv build/lib*/torch/include/* libtorch/include/

# Copy over all of the cmake files
cp -rv build/lib*/torch/share/*   libtorch/share/

## save the location so we can use it later
export TORCH_PATH=$(pwd)/libtorch

##-- now into the "torch" R package
cd ..

## just to make things a bit faster
export MAKEFLAGS=-j64

## there are no release branches, so go for main
git clone https://github.com/mlverse/torch.git

## build lantern
cd torch/src/lantern
## bugfix: this was need since getDefaultCUDAGenerator doesn't exist in CUDAHooks
## (confused with at::cuda::detail::getDefaultCUDAGenerator() perhaps?)
sed -i 's:getDefaultCUDAGenerator:getDefaultGenerator:g' src/Cuda.cpp
mkdir build
cd build
## make sure CUDA from the top of the script is correct
## otherwise lantern will fail to find some deps
CUDA=$CUDA cmake -DTORCH_PATH=${TORCH_PATH} ..
make $MAKEFLAGS
make install DESTDIR=`pwd`/dst
LANTERN_ROOT=`pwd`/dst/usr/local

## back to torch root
cd ../../..

## copy libtorch and lantern into inst/lib
mkdir inst/lib
cp ${TORCH_PATH}/lib/*.so inst/lib/
cp ${LANTERN_ROOT}/lib/*.so inst/lib/

## done, phew -- just install
cd ..
R CMD INSTALL torch

[s-u]

Minor note: one additional, optional dependency is Magma - GPU-based LAPACK which was not included above. If it is not already installed, compile static magma library which is just a standard cmake install:

curl -L https://icl.utk.edu/projectsfiles/magma/downloads/magma-2.7.2.tar.gz | tar xz
cd magma-2.7.2
mkdir build
cd build
cmake -DBUILD_SHARED_LIBS=no -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_POSITION_INDEPENDENT_CODE=ON ..
make -j64 && make install

(set -DGPU_TARGET to expand the supported gpu architectures as needed)

[dfalbel]

Thanks @s-u You are right, we should definitely have a single liner cmake call that builds both lantern and libtorch.
Maybe adding another option that uses cmake's ExternalProject module and builds libtorch as part of building lantern.

FWIW this works for building libtorch (at least on MacOS):

https://github.com/mlverse/libtorch-mac-m1/blob/7e909536f70fa7992813d487a6120c4532047c06/.github/workflows/libtorch-x86_64.yaml#L30-L49

And is quite elegant in correctly preparing the libtorch.zip bundle. Of course, you would still need to manually build some of the optional deps.

[s-u]

@dfalbel thanks, the repo you linked definitely helps! That would have saved me a few hours ;).

I wasn't even looking for a single-liner but rather any possible documentation since it's entirely absent. It's all a mess for silly reasons that may not be obvious to you as the author - e.g., I was assuming that lantern is the other lantern project upstream which you included and only digging into the sources revealed that it's a C++ wrapper you wrote as part of torch that you gave the same name and not related to any other lantern :). Also libtorch is built entirely differently by the pytortch team than what you do. So simply adding a few lines to the README (or point to another md file with that info) about what the components are and how they are built would go along way.

Along those lines: the https://torch.mlverse.org/ website is awesome for users and PR, but I couldn't find links to any actual technical content about the package itself ("getting technical" is not it :P), so I had to essentially reverse-engineer everything. I wouldn't wish to anyone else to have to that that again ;) (And I'd be happy to update that info with more details - like the different CUDA arch flags etc.)

[dfalbel]

Indeed we own a lot of improvements regarding documentation for package contributors. We do have an article here: https://torch.mlverse.org/docs/articles/modifying-source-code

But for some reason it didn't get indexed in the website menus.