From 50e3d0d7b590136d2d43c3dca6f77cf8f2b5ec6c Mon Sep 17 00:00:00 2001 From: Jason Fairchild Date: Tue, 23 Jul 2024 23:00:54 +1000 Subject: [PATCH 1/2] 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 From ea43e5ea00615ee1dc46264306f5cf246ad9fc56 Mon Sep 17 00:00:00 2001 From: Jason Fairchild Date: Thu, 25 Jul 2024 22:51:10 +1000 Subject: [PATCH 2/2] docs(#91): Tighten up CONTRIBUTING.md --- docs/CONTRIBUTING.md | 117 +++++++++++++------------------------------ 1 file changed, 35 insertions(+), 82 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 67abadda..30edd1b0 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -15,117 +15,70 @@ For more information on how to get started, read on! ## Setting Up Your Build Environment -To build **Vivify** you need the following dependencies:- +First install the required build dependencies using your system package manager -**MacOS:** +- yarn +- make +- zip - TODO: Mac instructions +Next you need to make sure you have Node.js installed -**Arch Linux/Manjaro:** - - 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. +Node.js may be available with your OS or in your distro 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:- +> [!NOTE] +> The version of **Node.js** shipped with some Linux distributions will fail to +> build **Vivify**, in that case you should refer to the **nvm** documentation +> to install the latest version - curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash +## Running Vivify for Development -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`) +First clone and open the **Vivify** repository, then run `yarn` to download +Node.js dependencies -Now you can install the latest version of Node.js:- + yarn - nvm install node +**Vivify** has a development mode that will:- -> [!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]: +1. Run the server on port `3000` instead of the usual port of `31622`; +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. -## Building Vivify +To run the **Vivify** server in development mode:- -First clone and open the **Vivify** repository + yarn dev - git clone https://github.com/jannis-baum/Vivify.git - cd Vivify +Once the development server is running, you can connect as many instances as you +like:- -Run `yarn` to download all node dependencies + yarn viv . - yarn + Using `yarn viv` will connect to the development server on port 3000 -Then build **Vivify** by running `make ` where *OS-family* is your -operating system (Linux or MacOS) +> [!TIP] +> You can replace `.` with any file or directory -**MacOS:** +## Installing Vivify - make macos +To install **Vivify** for use outside of your development environment, first +define your install location by running the configuration script that takes an +install path as a parameter: `./configure ` -**Linux:** +For example:- - make linux + ./configure ~/.local/bin -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:- +Then run `make install` to build and install **Vivify** - ./configure ~/.local/bin make install -Once installed you can launch **viv** by calling `viv ` +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