mirror of
https://github.com/Cog-Creators/Red-DiscordBot.git
synced 2025-11-05 18:58:53 -05:00
[Docs] Restructure venv instructions (put them in install guides) (#3495)
* docs: restructure venv instructions * docs: add a warning about PowerShell usage
This commit is contained in:
jack1142
GitHub
parent
48e2dad3a4
commit
3991a2d88f
39
docs/about_venv.rst
Normal file
39
docs/about_venv.rst
Normal file
@ -0,0 +1,39 @@
|
||||
.. _about-venvs:
|
||||
|
||||
==========================
|
||||
About Virtual Environments
|
||||
==========================
|
||||
Creating a virtual environment is really easy and usually prevents many common installation
|
||||
problems.
|
||||
|
||||
**What Are Virtual Environments For?**
|
||||
|
||||
Virtual environments allow you to isolate Red's library dependencies, cog dependencies and python
|
||||
binaries from the rest of your system. There is no performance overhead to using virtual environment
|
||||
and it saves you from a lot of troubles during setup. It also makes sure Red and its dependencies
|
||||
are installed to a predictable location which makes uninstalling Red as simple as removing a single folder,
|
||||
without worrying about losing your data or other things on your system becoming broken.
|
||||
|
||||
|
||||
--------------------------------------------
|
||||
Virtual Environments with Multiple Instances
|
||||
--------------------------------------------
|
||||
If you are running multiple instances of Red on the same machine, you have the option of either
|
||||
using the same virtual environment for all of them, or creating separate ones.
|
||||
|
||||
.. note::
|
||||
|
||||
This only applies for multiple instances of V3. If you are running a V2 instance as well,
|
||||
you **must** use separate virtual environments.
|
||||
|
||||
The advantages of using a *single* virtual environment for all of your V3 instances are:
|
||||
|
||||
- When updating Red, you will only need to update it once for all instances (however you will still need to restart all instances for the changes to take effect)
|
||||
- It will save space on your hard drive
|
||||
|
||||
On the other hand, you may wish to update each of your instances individually.
|
||||
|
||||
.. important::
|
||||
|
||||
Windows users with multiple instances should create *separate* virtual environments, as
|
||||
updating multiple running instances at once is likely to cause errors.
|
||||
@ -14,7 +14,7 @@ Welcome to Red - Discord Bot's documentation!
|
||||
|
||||
install_windows
|
||||
install_linux_mac
|
||||
venv_guide
|
||||
about_venv
|
||||
autostart_systemd
|
||||
autostart_pm2
|
||||
|
||||
|
||||
@ -348,8 +348,82 @@ Continue by `creating-venv-linux`.
|
||||
Creating a Virtual Environment
|
||||
------------------------------
|
||||
|
||||
.. tip::
|
||||
|
||||
If you want to learn more about virtual environments, see page: `about-venvs`
|
||||
|
||||
We require installing Red into a virtual environment. Don't be scared, it's very
|
||||
straightforward. See the section `installing-in-virtual-environment`.
|
||||
straightforward.
|
||||
|
||||
You have 2 options:
|
||||
|
||||
* :ref:`using-venv` (quick and easy, involves just two commands)
|
||||
* :ref:`using-pyenv-virtualenv` (only available and recommended when you installed Python with pyenv)
|
||||
|
||||
----
|
||||
|
||||
.. _using-venv:
|
||||
|
||||
**************
|
||||
Using ``venv``
|
||||
**************
|
||||
This is the quickest way to get your virtual environment up and running, as `venv` is shipped with
|
||||
python.
|
||||
|
||||
First, choose a directory where you would like to create your virtual environment. It's a good idea
|
||||
to keep it in a location which is easy to type out the path to. From now, we'll call it
|
||||
``redenv`` and it will be located in your home directory.
|
||||
|
||||
Create your virtual environment with the following command::
|
||||
|
||||
python3.8 -m venv ~/redenv
|
||||
|
||||
And activate it with the following command::
|
||||
|
||||
source ~/redenv/bin/activate
|
||||
|
||||
.. important::
|
||||
|
||||
You must activate the virtual environment with the above command every time you open a new
|
||||
shell to run, install or update Red.
|
||||
|
||||
Continue by `installing-red-linux-mac`.
|
||||
|
||||
----
|
||||
|
||||
.. _using-pyenv-virtualenv:
|
||||
|
||||
**************************
|
||||
Using ``pyenv virtualenv``
|
||||
**************************
|
||||
|
||||
Using ``pyenv virtualenv`` saves you the headache of remembering where you installed your virtual
|
||||
environments. This option is only available if you installed Python with pyenv.
|
||||
|
||||
First, ensure your pyenv interpreter is set to python 3.8.1 or greater with the following command::
|
||||
|
||||
pyenv version
|
||||
|
||||
Now, create a virtual environment with the following command::
|
||||
|
||||
pyenv virtualenv <name>
|
||||
|
||||
Replace ``<name>`` with whatever you like. If you ever forget what you named it,
|
||||
you can always use the command ``pyenv versions`` to list all virtual environments.
|
||||
|
||||
Now activate your virtualenv with the following command::
|
||||
|
||||
pyenv shell <name>
|
||||
|
||||
.. important::
|
||||
|
||||
You must activate the virtual environment with the above command every time you open a new
|
||||
shell to run, install or update Red. You can check out other commands like ``pyenv local`` and
|
||||
``pyenv global`` if you wish to keep the virtualenv activated all the time.
|
||||
|
||||
Continue by `installing-red-linux-mac`.
|
||||
|
||||
.. _pyenv-installer: https://github.com/pyenv/pyenv-installer/blob/master/README.rst
|
||||
|
||||
.. _installing-red-linux-mac:
|
||||
|
||||
|
||||
@ -68,8 +68,35 @@ Manually installing dependencies
|
||||
Creating a Virtual Environment
|
||||
------------------------------
|
||||
|
||||
.. tip::
|
||||
|
||||
If you want to learn more about virtual environments, see page: `about-venvs`
|
||||
|
||||
We require installing Red into a virtual environment. Don't be scared, it's very
|
||||
straightforward. See the section `installing-in-virtual-environment`.
|
||||
straightforward.
|
||||
|
||||
First, choose a directory where you would like to create your virtual environment. It's a good idea
|
||||
to keep it in a location which is easy to type out the path to. From now, we'll call it
|
||||
``redenv`` and it will be located in your home directory.
|
||||
|
||||
Start with opening a command prompt (open Start, search for "command prompt", then click it)
|
||||
|
||||
.. warning::
|
||||
|
||||
These commands will not work in PowerShell - you have to use command prompt as said above.
|
||||
|
||||
Then create your virtual environment with the following command::
|
||||
|
||||
py -3.8 -m venv "%userprofile%\redenv"
|
||||
|
||||
And activate it with the following command::
|
||||
|
||||
"%userprofile%\redenv\Scripts\activate.bat"
|
||||
|
||||
.. important::
|
||||
|
||||
You must activate the virtual environment with the above command every time you open a new
|
||||
Command Prompt to run, install or update Red.
|
||||
|
||||
--------------
|
||||
Installing Red
|
||||
@ -78,8 +105,7 @@ Installing Red
|
||||
.. attention:: You may need to restart your computer after installing dependencies
|
||||
for the PATH changes to take effect.
|
||||
|
||||
1. Open a command prompt (open Start, search for "command prompt", then click it)
|
||||
2. Run **one** of the following set of commands, depending on what extras you want installed
|
||||
Run **one** of the following set of commands, depending on what extras you want installed
|
||||
|
||||
* Normal installation:
|
||||
|
||||
|
||||
@ -1,142 +0,0 @@
|
||||
.. _installing-in-virtual-environment:
|
||||
|
||||
=======================================
|
||||
Installing Red in a Virtual Environment
|
||||
=======================================
|
||||
Creating a virtual environment is really easy and usually prevents many common installation
|
||||
problems. Firstly, simply choose how you'd like to create your virtual environment:
|
||||
|
||||
* :ref:`using-venv` (quick and easy, involves two commands)
|
||||
* :ref:`using-pyenv-virtualenv` (recommended if you installed Python with pyenv)
|
||||
|
||||
**What Are Virtual Environments For?**
|
||||
|
||||
Virtual environments allow you to isolate Red's library dependencies, cog dependencies and python
|
||||
binaries from the rest of your system. It also makes sure Red and its dependencies are installed to
|
||||
a predictable location. It makes uninstalling Red as simple as removing a single folder, without
|
||||
worrying about losing your data or other things on your system becoming broken.
|
||||
|
||||
.. _using-venv:
|
||||
|
||||
--------------
|
||||
Using ``venv``
|
||||
--------------
|
||||
This is the quickest way to get your virtual environment up and running, as `venv` is shipped with
|
||||
python.
|
||||
|
||||
First, choose a directory where you would like to create your virtual environment. It's a good idea
|
||||
to keep it in a location which is easy to type out the path to. From now, we'll call it
|
||||
``redenv`` and it will be located in your home directory.
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
``venv`` on Linux or Mac
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Create your virtual environment with the following command::
|
||||
|
||||
python3.8 -m venv ~/redenv
|
||||
|
||||
And activate it with the following command::
|
||||
|
||||
source ~/redenv/bin/activate
|
||||
|
||||
.. important::
|
||||
|
||||
You must activate the virtual environment with the above command every time you open a new
|
||||
shell to run, install or update Red.
|
||||
|
||||
Continue reading `below <after-activating-virtual-environment>`.
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
``venv`` on Windows
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
Create your virtual environment with the following command::
|
||||
|
||||
py -3.8 -m venv %userprofile%\redenv
|
||||
|
||||
And activate it with the following command::
|
||||
|
||||
%userprofile%\redenv\Scripts\activate.bat
|
||||
|
||||
.. important::
|
||||
|
||||
You must activate the virtual environment with the above command every time you open a new
|
||||
Command Prompt to run, install or update Red.
|
||||
|
||||
Continue reading `below <after-activating-virtual-environment>`.
|
||||
|
||||
.. _using-pyenv-virtualenv:
|
||||
|
||||
--------------------------
|
||||
Using ``pyenv virtualenv``
|
||||
--------------------------
|
||||
|
||||
.. note::
|
||||
|
||||
This is for non-Windows users only.
|
||||
|
||||
Using ``pyenv virtualenv`` saves you the headache of remembering where you installed your virtual
|
||||
environments. If you haven't already, install pyenv with `pyenv-installer`_.
|
||||
|
||||
First, ensure your pyenv interpreter is set to python 3.8.1 or greater with the following command::
|
||||
|
||||
pyenv version
|
||||
|
||||
Now, create a virtual environment with the following command::
|
||||
|
||||
pyenv virtualenv <name>
|
||||
|
||||
Replace ``<name>`` with whatever you like. If you forget what you named it, use the command ``pyenv
|
||||
versions``.
|
||||
|
||||
Now activate your virtualenv with the following command::
|
||||
|
||||
pyenv shell <name>
|
||||
|
||||
.. important::
|
||||
|
||||
You must activate the virtual environment with the above command every time you open a new
|
||||
shell to run, install or update Red. You can check out other commands like ``pyenv local`` and
|
||||
``pyenv global`` if you wish to keep the virtualenv activated all the time.
|
||||
|
||||
Continue reading `below <after-activating-virtual-environment>`.
|
||||
|
||||
.. _pyenv-installer: https://github.com/pyenv/pyenv-installer/blob/master/README.rst
|
||||
|
||||
----
|
||||
|
||||
.. _after-activating-virtual-environment:
|
||||
|
||||
Once activated, your ``PATH`` environment variable will be modified to use the virtual
|
||||
environment's python executables, as well as other executables like ``pip``.
|
||||
|
||||
From here, install Red using the commands listed on your installation guide (`Windows
|
||||
<installing-red-windows>` or `Non-Windows <installing-red-linux-mac>`).
|
||||
|
||||
.. note::
|
||||
|
||||
The alternative to activating the virtual environment each time you open a new shell is to
|
||||
provide the full path to the executable. This will automatically use the virtual environment's
|
||||
python interpreter and installed libraries.
|
||||
|
||||
--------------------------------------------
|
||||
Virtual Environments with Multiple Instances
|
||||
--------------------------------------------
|
||||
If you are running multiple instances of Red on the same machine, you have the option of either
|
||||
using the same virtual environment for all of them, or creating separate ones.
|
||||
|
||||
.. note::
|
||||
|
||||
This only applies for multiple instances of V3. If you are running a V2 instance as well,
|
||||
You **must** use separate virtual environments.
|
||||
|
||||
The advantages of using a *single* virtual environment for all of your V3 instances are:
|
||||
|
||||
- When updating Red, you will only need to update it once for all instances (however you will still need to restart all instances for the changes to take effect)
|
||||
- It will save space on your hard drive
|
||||
|
||||
On the other hand, you may wish to update each of your instances individually.
|
||||
|
||||
.. important::
|
||||
|
||||
Windows users with multiple instances should create *separate* virtual environments, as
|
||||
updating multiple running instances at once is likely to cause errors.
|
||||
Loading…
x
Reference in New Issue
Block a user