From d89d0b9c390e83e2ec2be80786dfe2cf0db701b2 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Sat, 13 Mar 2021 16:43:00 +0000 Subject: [PATCH] Big reorganisation to hopefully make everything clearer. * It goes through the necessary steps in a more logical order (python, check pip, check tkinter, only then get source, use pip, run application). As a result the necessary instructions for macOS should be clearer. --- Running-from-source.md | 100 ++++++++++++++++++++++++++++------------- 1 file changed, 68 insertions(+), 32 deletions(-) diff --git a/Running-from-source.md b/Running-from-source.md index b416782..3097679 100644 --- a/Running-from-source.md +++ b/Running-from-source.md @@ -1,57 +1,93 @@ -Running from source -=== +#Running from source You will currently need at least Python 3.7.x to run `stable` code. In order to run `develop` you will need Python 3.8.x or higher (3.9.x has had some testing). -1. On MacOS you will likely need a Python install from [the official Python - website](https://www.python.org/), rather than using HomeBrew. See - [#670 Update requirements.txt for MacOS](https://github.com/EDCD/EDMarketConnector/issues/670) - for discussion about this. +## Ensure Python is installed -1. You have two choices: - 1. Using a zip of the latest stable source. Download and extract the +On Windows or macOS Download and install an appropriate version from +[python.org](https://python.org). Do **not use HomeBrew** on macOS, that +version is known to have a broken `tk`. See [#670 Update requirements.txt for +MacOS](https://github.com/EDCD/EDMarketConnector/issues/670) +for discussion about this. + + +On Linux you should use your distribution's Python 3.x packages. Note that at +least Debian 10 still has 2.7.x as `python` and `pip`, and you will need to +specify `python3` (from the package of that name) and `pip3` (from +`python3-pip` in the commands below in order to use a 3.x version. + +As and when we move from Python 3.7 to 3.8 or beyond you might find that +your Linux distribution is still only shipping Python 3.7, in which case +you will need to install a later version separately and ensure you are +using the correct version. You already need at least Python 3.8.x to use our +`develop` branch code. + +## Ensure you have working `pip` + +Ensure you have `pip` or `pip3` installed, check with `pip --version` or +`pip3 --version`. + +On Debian you will need the `python3-pip` package installed. + +Otherwise see [Installing pip](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#installing-pip). + +##Ensure you have tkinter installed + +If using a python.org package it will include this. + +On Debian / Ubuntu / other Debian derivatives the package you need to install +is `python3-tk`. + +## Obtain a copy of the application source + +Choose one of the following: + +1. Using a zip of the latest stable source. Download and extract the [latest stable source code](https://github.com/EDCD/EDMarketConnector/archive/stable.zip). - 1. OR Clone and checkout the source using git: - 1. `cd ` - 1. `git clone https://github.com/EDCD/EDMarketConnector.git` - 1. `cd EDMarketConnector` - 1. `git checkout stable` +1. OR Clone and checkout the source using git: + 1. `cd ` + 1. `git clone https://github.com/EDCD/EDMarketConnector.git` + 1. `cd EDMarketConnector` + 1. `git checkout stable` - As per [Contributing.md](https://github.com/EDCD/EDMarketConnector/blob/main/Contributing.md#git-branch-structure-and-tag-conventions) +As per [Contributing.md](https://github.com/EDCD/EDMarketConnector/blob/main/Contributing.md#git-branch-structure-and-tag-conventions) `stable` will contain the latest released code, or possibly some extra commits leading up to the next release. If you're feeling slightly braver you could use the [main branch source code](https://github.com/EDCD/EDMarketConnector/archive/main.zip) (or `git checkout main`) instead which might contain newer code that we consider stable enough for the next release. - *NB: Do not use the `master` branch*, it's almost empty! The name is - deprecated and we use `main` instead. +**NB: Do not use the `master` branch**, it's almost empty! The name is +deprecated and we use `main` instead. -1. Ensure you have 'pip' or 'pip3' installed, see [Installing pip](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#installing-pip). +## Use `pip` to install application requirements -1. Ensure additional necessary Python modules are installed with `pip install -r requirements.txt` . - * Note that on Debian (at least up to and including 10.x aka 'Buster') you'll `pip3 install -r requirements.txt` . - * If you get 'command not found' or similar for the 'pip' command then +1. Ensure additional necessary Python modules are installed with + + `pip install -r requirements.txt` . + + * Note that on Debian (at least up to and including 10.x aka 'Buster') + you'll need `pip3 install -r requirements.txt` . + * If you get 'command not found' or similar for the 'pip' command then first try: `python -m pip --user install pip`. -1. Ensure you have tkinter installed if required (such as on Linux) - * On Debian / Ubuntu / other Debian derivatives the package you want is - `python3-tk`. +## Run the application -1. Run this application: - - * Linux: `./EDMarketConnector.py` . - * Mac: `python ./EDMarketConnector.py` . - * Windows: `EDMarketConnector.py` . + * Linux: `python3 EDMarketConnector.py` . + * Mac: `python3 EDMarketConnector.py` . + * Windows: `EDMarketConnector.py` . -Command-line --------- +#Command-line -The command-line program `EDMC.py` writes the current system and station (if docked) to stdout and optionally writes player status, ship locations, ship loadout and/or station data to file. -This program requires that the user has performed [setup](#setup) and verification through the app. +The command-line program `EDMC.py` writes the current system and station (if +docked) to stdout and optionally writes player status, ship locations, ship +loadout and/or station data to file. + +This program requires that the user has performed Frontier +Authentication through the main application. Arguments: