diff --git a/docs/install.md b/docs/install.md index 398f7e3..cf54cb4 100644 --- a/docs/install.md +++ b/docs/install.md @@ -7,11 +7,27 @@ Before proceeding, please note that MVT requires Python 3.6+ to run. While it sh First install some basic dependencies that will be necessary to build all required tools: ```bash -sudo apt install python3 python3-pip libusb-1.0-0 sqlite3 +sudo apt install python3 python3-venv python3-pip sqlite3 libusb-1.0-0 ``` *libusb-1.0-0* is not required if you intend to only use `mvt-ios` and not `mvt-android`. +(Recommended) Set up `pipx` + +For Ubuntu 23.04 or above: +```bash +sudo apt install pipx +pipx ensurepath +``` + +For Ubuntu 22.04 or below: +``` +python3 -m pip install --user pipx +python3 -m pipx ensurepath +``` + +Other distributions: check for a `pipx` or `python-pipx` via your package manager. + When working with Android devices you should additionally install [Android SDK Platform Tools](https://developer.android.com/studio/releases/platform-tools). If you prefer to install a package made available by your distribution of choice, please make sure the version is recent to ensure compatibility with modern Android devices. ## Dependencies on macOS @@ -21,7 +37,7 @@ Running MVT on macOS requires Xcode and [homebrew](https://brew.sh) to be instal In order to install dependencies use: ```bash -brew install python3 libusb sqlite3 +brew install python3 pipx libusb sqlite3 ``` *libusb* is not required if you intend to only use `mvt-ios` and not `mvt-android`. @@ -42,24 +58,43 @@ It is recommended to try installing and running MVT from [Windows Subsystem Linu ## Installing MVT -If you haven't done so, you can add this to your `.bashrc` or `.zshrc` file in order to add locally installed PyPI binaries to your `$PATH`: +### Installing from PyPI with pipx (recommended) +1. Install `pipx` following the instructions above for your OS/distribution. Make sure to run `pipx ensurepath` and open a new terminal window. +2. ```bash + pipx install mvt + ``` +You now should have the `mvt-ios` and `mvt-android` utilities installed. If you run into problems with these commands not being found, ensure you have run `pipx ensurepath` and opened a new terminal window. + +### Installing from PyPI directly into a virtual environment +You can use `pipenv`, `poetry` etc. for your virtual environment, but the provided example is with the built-in `venv` tool: + +1. Create the virtual environment in a folder in the current directory named `env`: ```bash -export PATH=$PATH:~/.local/bin +python3 -m venv env ``` -Then you can install MVT directly from [PyPI](https://pypi.org/project/mvt/) - +2. Activate the virtual environment: ```bash -pip3 install mvt +source env/bin/activate ``` -If you want to have the latest features in development, you can install MVT directly from the source code. If you installed MVT previously from pypi, you should first uninstall it using `pip3 uninstall mvt` and then install from the source code: +3. Install `mvt` into the virtual environment: +```bash +pip install mvt +``` + +The `mvt-ios` and `mvt-android` utilities should now be available as commands whenever the virtual environment is active. + +### Installing from git source with pipx +If you want to have the latest features in development, you can install MVT directly from the source code in git. ```bash -git clone https://github.com/mvt-project/mvt.git -cd mvt -pip3 install . +pipx install --force git+https://github.com/mvt-project/mvt.git ``` You now should have the `mvt-ios` and `mvt-android` utilities installed. + +**Notes:** +1. The `--force` flag is necessary to force the reinstallation of the package. +2. To revert to using a PyPI version, it will be necessary to `pipx uninstall mvt` first.