Update INSTALL.md to work with a dedicated virtual environment (#2195)

* Update INSTALL.md to work with a dedicated virtual environment

* Clearer tool wording

* Bump fallback version for impending release

* Bump tools version for impending release

* Removing advanced installations

* Update fprime-gds requirement

---------

Co-authored-by: thomas-bc <[email protected]>

Autocoders/Python/src/fprime_ac/utils/version.py

@@ -2,7 +2,7 @@
 import os
 import subprocess
 
-FALLBACK_VERSION = "v3.3.0"  # Keep up-to-date on release tag
+FALLBACK_VERSION = "v3.3.1"  # Keep up-to-date on release tag
 
 
 def get_version_str(working_dir, fallback=FALLBACK_VERSION):

docs/INSTALL.md

@@ -9,36 +9,59 @@ This installation guide is specifically designed to enable individuals and resea
 
 **Note:** See the troubleshooting section at the bottom for help resolving common issues found during F´ installs.
 
-## Requirements
+**Sections:**
+- [System Requirements](#system-requirements)
+- [Setting Up the Development Environment](#setting-up-the-development-environment)
+- [Creating a New Project](#creating-a-new-project)
+- [Working With An Existing Project](#working-with-an-existing-project)
+- [Troubleshooting](#troubleshooting)
+
+
+## System Requirements
 
 F´ depends on several items before the user should attempt to install it. These requirements are listed below and the user should ensure they are installed before proceeding with this guide.
 
 Requirements:
 
-1. Linux or macOS operating system
+1. Linux, macOS, or WSL on Windows
 2. git
 3. [CMake 3.16](https://cmake.org/download/) or newer. CLI tool must be available on the system path.
 4. CLang or GNU C and C++ compilers (e.g. gcc and g++)
-5. [Python 3.7+](https://www.python.org/downloads/), virtual environments, and PIP
+5. [Python 3.8+](https://www.python.org/downloads/), virtual environments, and PIP
 
 **Note:** OS-specific notes are in the [Troubleshooting](#Troubleshooting) section below.
 
-### Bootstrapping the F´ Development Environment
+## Setting Up the Development Environment
+
+The ecosystem of tools supporting F´ is installed as python packages available via PIP. To setup F´ tools, you should create a [virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/), activate it, and install the latest version of fprime-tools.
 
-The ecosystem of tools supporting F´ is installed as python packages available via PIP.
+1. Create the virtual environment:
 
+```bash
+python3 -m venv fprime-venv
 ```
-pip install fprime-tools
+> You should create a new virtual environment for each new F´ project. The name `fprime-venv` may be changed.
+
+2. Activate the virtual environment
+
+```bash
+. fprime-venv/bin/activate
 ```
+> Remember to activate the virtual environment whenever you work with this F´  project.
 
-> You may need to install with `sudo` or install into a [virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/).
+2. Install F´  tools
+```
+pip install -U fprime-tools
+```
+>
 
-### Creating a New F´ Project
+## Creating a New Project
 
-The entrypoint to developing with F´ is creating a new project. This will clone the F´ repository and install the necessary tool versions for working with the specified version of F´.
+The entrypoint to developing with F´ is creating a new project. This will clone the F´ repository and install the full tool suite of the specified version for working with the selected version of F´.
 ```
 fprime-util new --project
 ```
+
 This command will ask for some input. Sample responses are below:
 ```
 project_name [MyProject]: MyProject
@@ -51,34 +74,19 @@ Choose from 1, 2 [1]: 1
 
 Next steps: [HelloWorld Tutorial](https://fprime-community.github.io/fprime-tutorial-hello-world/)
 
-## Advanced
-
-There are several advanced options users can consider while installing F´. However, users should be warned that some knowledge of our tools and versions is often required.
+## Working With An Existing Project
 
+Sometimes users wish to work with existing F´ projects. Once the project has been acquired, users should install the tools associated with that project. This is done with:
 
-### Installing Tab Completion
+1. Ensure a virtual environment for this project has been created and [activated](#setting-up-the-development-environment)
 
-Several of F´s command-line utilities support tab completion. To enable these tools to use it, see the [instructions here](UsersGuide/user/autocomplete.md).
+2. Download the project
+> When using `git` and submodules, remember to run `git submodule update --init --recursive`
 
+4. Install the required F´ tools version
+`pip install -r <project>/fprime/requirements.txt`
 
-### Installing Optional Components
-
-Some F´ packages contain optional components. These components can be installed including the option in square brackets.
-
-| Package                  | Description |
-|--------------------------|-------------|
-| fprime-tools[dev]        | Installs the Python development tools for working with F´ Python code |
-| fprime-gds[uart-adapter] | Installs the UART communication adapter for the F´ GDS |
-| fprime-gds[test-api-xls] | Installs excel logging for use within the integration test framework |
-
-
-> These packages are optional as they pull in many additional packages and libraries. These may not be supported on all systems.
-
-**Example:**
-```
-pip install fprime-gds[uart-adapter]
-```
-
+> Some projects ship their own `requirements.txt`.  Install using that file if it exists.
 
 ## Troubleshooting
 

requirements.txt

@@ -19,8 +19,8 @@ fprime-fpl-extract-xml==1.0.0
 fprime-fpl-layout==1.0.0
 fprime-fpl-write-pic==1.0.0
 fprime-fpp==1.3.0
-fprime-gds==3.3.0
-fprime-tools==3.3.1
+fprime-gds==3.3.2
+fprime-tools==3.3.2
 fprime-visual==1.0.0
 gcovr==6.0
 idna==3.4
@@ -37,6 +37,7 @@ pexpect==4.8.0
 pluggy==1.2.0
 ptyprocess==0.7.0
 Pygments==2.15.1
+pyserial==3.5
 pytest==7.4.0
 python-dateutil==2.8.2
 python-slugify==8.0.1