From 0d61edaff74fc5e4bcd1be9b189a9e73b0e929a5 Mon Sep 17 00:00:00 2001 From: Delyan Angelov Date: Mon, 14 Aug 2023 23:44:16 +0300 Subject: [PATCH] docs: add doc/packaging_v_for_distributions.md (#19139) --- doc/docs.md | 3 + doc/packaging_v_for_distributions.md | 133 +++++++++++++++++++++++++++ 2 files changed, 136 insertions(+) create mode 100644 doc/packaging_v_for_distributions.md diff --git a/doc/docs.md b/doc/docs.md index 31046ae797..732e35ace7 100644 --- a/doc/docs.md +++ b/doc/docs.md @@ -39,6 +39,9 @@ If V is already installed on a machine, it can be upgraded to its latest version by using the V's built-in self-updater. To do so, run the command `v up`. +## Packaging V for distribution +See the [notes on how to prepare a package for V](doc/packaging_v_for_distributions.md) . + ## Getting started You can let V automatically set up the bare-bones structure of a project for you diff --git a/doc/packaging_v_for_distributions.md b/doc/packaging_v_for_distributions.md new file mode 100644 index 0000000000..67b5060e03 --- /dev/null +++ b/doc/packaging_v_for_distributions.md @@ -0,0 +1,133 @@ +Packaging V +============= + +Thank you for supporting V and its users, and for creating, *and maintaining* a package for it. + +V is still changing, and installing it from source, is still the *recommended way*, to +distribute it to most V users. + +However, we understand that sooner or later people will want to adapt the +upstream source to their favorite distro/platform, and that usually involves preparing a package +that will be installed and updated (using a standardized package manager) just like all other +programs in the distribution. + +This document is for the brave people that want to prepare and +*maintain* such a package. + +Good luck. + +Details +============= + +Preparing a package of the current version of V for distribution, has some peculiarities +that must be understood, and taken into account, for the best experience of the users of +your package, for your sanity, and for easier troubleshooting of problems when they happen. + +1) V builds many of its commands on demand, to save both time and space. The source of the +entry points of those commands is stored in the folder cmd/tools/ . If you are preparing a +prebuilt V package, that needs to ensure that the final package after installation will be +read only, that will be a problem, since V will try to write to its cmd/tools/ folder. +To prevent that, you need to build *all* the commands/executables in that folder *ahead of time*. +This can be done by the command `v build-tools`. + +2) Tell V to not try to recompile its tools anymore. To do that, V supports checking for the +presence of a file named `cmd/tools/.disable_autorecompilation` (that file is missing by default +in the cloned version of V). +Note: the content of this file does not matter, *only its presence does*. + +3) V has a tool/command, that enables rapid updating from the latest master branch in its main +repository. That tool is `v up`. Most distros however, have the policy of not allowing packages +to make modifications to themselves. Instead, they require the user to use their package manager, +provided by the distro/platform. + +To facilitate that, it is usually best for all involved if you, as a package maintainer, remove +or replace cmd/tools/vself.v, with a short v program, that advises the final V user to use the +package manager tool, or to use a V installed from source instead. + +4) Another V feature/command that can interfere with read only packaging is `v self`. We +recommend that you disable this command as well, by replacing cmd/tools/vself.v with a small +V program that informs the user that `v self` is not recommended when used with a packaged +version of V, and then advises the user to install V from source if he wants to use `v self`. + +5) The V source repo contains sizable folders like `.git/` and `thirdparty/tcc/.git/` which will +not be needed by users of packages (they are not useful if `v up` is disabled, +as recommended previously). Some other files, such as `Makefile`, `make.bat`, and `GNUmakefile` +will not be used either, so they can also be safely removed. + +Depending on how stripped you want your package, you can remove the examples/ folder as well. +It is usually good to have examples, but they could be in a separate package. + +If a user attempts to compile the examples in that folder, it +will not work in a read-only package (because the executables are put right next to the +source `.v` files by default, unless `-o path_to_executable_name` is used). + +6) Location of vlib/ . V expects, that its vlib/ folder, will be located right next to its +executable, and that is currently hard to customize. It will be changed, if there is enough +interest from package maintainers, expressed on the V issue tracker: +https://github.com/vlang/v/issues + +*However, you can* leave the executable in say /opt/vlang/v, with vlib/ in /opt/vlang/vlib/ , +then put a symlink from `/opt/vlang/v` to whatever folder that is on the user's PATH on your +distro, i.e.: `sudo ln -s /opt/vlang/v /usr/bin/v` or `sudo ln -s /opt/vlang/v /bin/v` . + +7) Location of the V executable can be controlled by setting the env variable VEXE. +It defaults to the absolute path of the V executable. + +8) Location of the modules folder for `v install` can be controlled by setting the env variable +named `VMODULES`. By default, modules are installed to `~/.vmodules`, +(`C:\Users\\.vmodules` on Windows). + +9) Location of the folder used by V for its temporary files can be controlled by setting the env +variable `VTMP`. By default, the system TEMP folder is used. + +10) Setting additional V flags for each compilation can be done by setting the env variable +`VFLAGS`. + +Note: points 7, 8, 9, 10 above, allow you to create a small launcher shell script, named `v`, +that sets those variables dynamically, according to the current user. You can then put +*this shell script* inside your package bin folder, i.e. inside /usr/bin/v, or /bin/v etc, +*instead of* the main V executable, or a symlink to it. + + +Example script to prepare the V source folder for packaging: +----------------------------------------------------------- + +Combining all of the above, here is a small script, that can be used as a base for your packaging +efforts: + +```sh +echo "println('use your package manager to update V," > cmd/tools/vup.v +echo "or if you want more recent V versions, just clone V from source," > cmd/tools/vup.v +echo "see https://github.com/vlang/v#installing-v-from-source')" > cmd/tools/vup.v + +echo "println('v self is disabled for packaged versions of V." > cmd/tools/vself.v +echo "Use your package manager, to update your V package instead." > cmd/tools/vself.v +echo "Alternatively, if you do want a more recent V version, just clone V from source," > cmd/tools/vself.v +echo "then follow the instructions here: https://github.com/vlang/v#installing-v-from-source')" > cmd/tools/vself.v + +v -prod -o v cmd/v ## build V itself with -prod +./v -prod build-tools ## build all tools with -prod too +touch ./cmd/tools/.disable_autorecompilation ## tell V to not try to recompile any tool anymore + +### Cleanup folders that would not be needed inside a pacakge, +### that is distrubuted separately from the V source repository: +rm -rf .git/ +rm -rf thirdparty/tcc/.git/ +``` + +Example `v` script for your bin folder: +-------------------------------------------------- + +```sh +#!/bin/bash + +export VEXE="/opt/vlang/v" +export VFLAGS="-cc /usr/bin/custom_cc" +export VCACHE="/var/cache/custom_vcache_folder" ## ~/.vmodules/cache by default +export VTMP="/var/cache/custom_tmp" +export VMODULES="$HOME/.vmodules" + +/opt/vlang/v $@ +``` + +Note: do not forget to also do this in your post install script: `chmod +x /usr/bin/v`