From 50e3d0d7b590136d2d43c3dca6f77cf8f2b5ec6c Mon Sep 17 00:00:00 2001 From: Jason Fairchild Date: Tue, 23 Jul 2024 23:00:54 +1000 Subject: [PATCH] docs(#91): Add detailed setup and build instructions to CONTRIBUTING.md --- README.md | 4 ++ docs/CONTRIBUTING.md | 137 ++++++++++++++++++++++++++++++++++++++----- 2 files changed, 125 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 458c09e7..adab006c 100644 --- a/README.md +++ b/README.md @@ -79,6 +79,10 @@ directory as an argument! See below for installation options. - run `./configure ` - run `make install` +> [!TIP] +> If you are having trouble building Vivify, or you'd like more detailed build +> instructions, see our [CONTRIBUTING](docs/CONTRIBUTING.md) page + ## Get help Is something not working or do you have any questions? [Start a diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 343257a7..67abadda 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -7,29 +7,134 @@ sure you follow the steps below: - Use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) with `#` as the context for all commits - Make sure you are not adding any merge commits to your branch -- Open a pull request & wait for a review!🩵 +- Open a pull request, include the issue it relates to in the body, for example: + `Closes #69` +- Wait for a review! 🩵 -## Developing environment +For more information on how to get started, read on! -After installing all dependencies with `yarn`, you can run +## Setting Up Your Build Environment -```sh -yarn dev -``` +To build **Vivify** you need the following dependencies:- -to run the development server for Vivify on port 3000 that will (1) -automatically reload when you make changes to the code, and (2), unlike the -installed version, not shut down when there are no connected clients. +**MacOS:** -With the development server running, use + TODO: Mac instructions -```sh -yarn viv -``` +**Arch Linux/Manjaro:** -instead of your installed Vivify executable. This will (1) connect to the -development server on port 3000 instead of running the installed server, and (2) -use the `viv` executable in the repository. + sudo pacman -S --needed yarn make zip + +**Fedora and derivatives:** + + sudo dnf install yarn make zip + +> [!NOTE] +> The version of **Node.js** shipped with some Linux distributions will fail to +> build **Vivify**, see the section below to install the latest node from **nvm** + +## Installing Node.js + +Node.js may be available with your OS or in your distros package manager. +Alternatively you can install the latest version of Node.js using **[Node +Version Manager](https://github.com/nvm-sh/nvm)** (**nvm**) + +To install **nvm** use:- + + curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash + +You will then need to reload your terminal by either closing it and opening a +new one or by re-sourcing your run commands (bash eg: `source ~/.bashrc`) + +Now you can install the latest version of Node.js:- + + nvm install node + +> [!TIP] +> You can return to the system version of node using `nvm use system` +> +> For more details on nvm usage or for troubleshooting installing nvm, visit the +> nvm [Documentation][1] page +> +> [1]: + +## Building Vivify + +First clone and open the **Vivify** repository + + git clone https://github.com/jannis-baum/Vivify.git + cd Vivify + +Run `yarn` to download all node dependencies + + yarn + +Then build **Vivify** by running `make ` where *OS-family* is your +operating system (Linux or MacOS) + +**MacOS:** + + make macos + +**Linux:** + + make linux + +If you want to install **Vivify** for use outside of your development +environmentm you can use `make install` but first you need to run the +`configure ` script, eg:- + + ./configure ~/.local/bin + make install + +Once installed you can launch **viv** by calling `viv ` + +> [!TIP] +> Ideally the install location should be included in your $PATH variable + +## Running Vivify for Development + +Once you have built **Vivify** or installed it using the pre-built binaries, you +can then run the **Vivify** server in development mode to try it out with +live-updates as you are coding. + +Using `yarn dev` to run **Vivify** in dev mode will:- + +1. Run `vivify-server` on port `3000` instead of the usual port of `31622` so + they can be run side by side; +2. Automatically reload when you make changes to the code; and +3. Unlike the installed version, not shut down when there are no connected + clients. + +First, use `yarn` to make sure all node dependencies are up to date + + yarn + +Then start the **Vivify** server in dev mode + + yarn dev + +Once the development server is running, you can connect as many instances as you +like using:- + + yarn viv . + +> [!TIP] +> Using `yarn viv` will connect to the development server on port 3000 instead +> of running the installed server, and will use the viv executable in the +> repository +> +> You can replace `.` with any path or filename + +## Troubleshooting + +### Build Error: Could not find the sentinel NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2 + +Cause: This happens on some Linux distros when using the distro packaged +versions of Node.js + +Resolution: Install the latest version of Node.js using nvm, See the +**Installing Node.js** section above ## Testing rendering