From a5e323ec4aa506b4c466e71f3944c6f5f9a8a4e7 Mon Sep 17 00:00:00 2001 From: Holger Frey Date: Tue, 19 Sep 2017 10:51:09 +0200 Subject: [PATCH] Added installation and update section to readme --- README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 62 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f6cdc13..0e911db 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,71 @@ -# arduino-timetable +arduino-timetable +================= Module to send commands to an Arduino based on a time table. -### Regarding Pyinstaller +Regarding Pyinstaller +--------------------- As of September 2017 the Pyinstaller version on PyPi is not ready for Python 3.6 and / or multiprocessing. I stopped trying to use Pyinstaller for distribution. The experiment is still available in the `pyinstaller` branch. + + +Installation +------------ + +As the only prerequisites, [Python (at least version 3.6)][python] must be +installed. An added bonus points, if [git][git] is also available. + +The installation should be performed in a python virtual environment. A virtual +environment (short: venv) isolates your base python installation from the +application and vice versa. This procedure is considered a standard procedure +when working with python applications and scripts. + +1. Choose the desired installation path (e.g. a folder in your home directory) +2. Create a python virtual environment with `python3 -m venv venv-ardunio-timetable` +3. Activate the environment: + - Posix: `source venv-ardunio-timetable/bin/activate` + - Windows: `venv-ardunio-timetable\Scripts\activate.bat` +4. [Download][download] the 'arduino-timetable' and unpack it or use git: + `git clone https://git.cpi.imtek.uni-freiburg.de/holgi/arduino-timetable.git` +5. Change to the new directory and install the software. I would recommend + to install the software as a 'development version', so that changes can be + made easily. Change to the folder where 'setup.py' is located and run + `pip install -e .` + +As of Version 0.1.0, this will also install one GUI-like application called +'magnetictrap'. It is located at the following paths: + +- Posix: `/bin/magnetictrap` +- Windows: `\Scripts\magnetictrap.exe` + +Don't move this file around. If you want to have a shortcut on the desktop or +somewhere else, please create a shortcut, alias or symbolic link - whatever it +is called on your system. + + +Updating +-------- + +Find out if the installation was done using git: + +- Open a command line and activate the environment. +- Change to the directory, where the 'setup.py' file of + the package is located +- Issue a `git status` command. If the result is something along the line + `fatal: Not a git repository`, git was not used for the installation +- Updating *with* git: + - Issue a `git pull origin` command to update the package +- Updating *without* git: + - Delete the folder that contains the 'setup.py' file + - [Download][download] the software again and unpack it +- Change to the folder where 'setup.py' is located and run +`pip install -e .` again to installe the applications + + +[python]: https://www.python.org/ +[git]: https://git-scm.com/ +[download]: https://git.cpi.imtek.uni-freiburg.de/holgi/arduino-timetable/archive/master.tar.gz