.. _installation: ========================== Developer Installation ========================== This section will guide you through the steps of installing and configuring your development environment. .. contents:: :local: Git client ============= Install a Git client to download the code. * On Windows you can use Git for windows: https://git-scm.com/download/win * On Linux and macOS, run this command: ``sudo apt install git`` Snooz Workspace ========================== First, manually create a folder called "snooz_workspace". This will be the root directory of the project and will contain at first only the snooz-toolbox repository. Snooz Toolbox repository ----------------------------------- The "snooz-toolbox" repository contains the main application code (the architecture of Snooz), which is essential for running the application in debug mode. However, you generally won't need to make modifications to this code unless you are working on a core feature of Snooz rather than on a specific tool. Clone this repository into your new "snooz_workspace" folder. Type this command line in a terminal (or "Git Bash" on Windows): ``git clone https://github.com/SnoozToolbox/snooz-toolbox.git`` .. note:: It is advised to tell Git to ignore the file **snooz.code-workspace** once downloaded because it will end up containing values that are specific to your installation. Run this command to do it: ``git update-index --skip-worktree ./snooz.code-workspace`` The repository "snooz-toolbox" also contains the tools, modules and apps released with the Snooz Toolbox, located in the resources folder. This allows you to run many tools using a single repository. However, any modifications to tools, modules and apps must be made in a different repository, which you will learn about in another step. Python ============= It's important to install Python version 3.10.X. The latest available version with an installer is version 3.10.11. You can download Python from the following link: https://www.python.org/downloads/release/python-31011/. .. note:: On Windows, it's advised to add the path to the Python executable to your environment variables. Follow this guide: https://realpython.com/add-python-to-path/ Default Python installation path: * Windows : C:/Users/UserName/AppData/Local/Programs/python * Linux and macOS : /usr/bin/python3.10 or /usr/local/bin/python3.10 .. warning:: On Linux, you need to manually install the Qt dev tools to access the designer tool. Type in the terminal ``sudo apt-get install qttools5-dev``. .. _virt_env: Python virtual environment ======================================= Software using Python often relies on various external libraries. Some software may require specific versions of these libraries, so it's strongly advised to create a Python virtual environment dedicated to your Snooz installation. You can follow this guide to set up a Python virtual environment: `Python venv `_ Name the virtual environment ``snooz_310_env`` and create it under the "snooz_workspace" folder. If you have multiple versions of Python installed, make sure you use Python 3.10 to create the virtual environment. Here an example of the command to type in the Command Prompt for Windows ``C:\Users\UserName\AppData\Local\Programs\Python\Python310\python -m venv .\snooz_310_env`` .. note:: On Linux, you might need to run this command first: ``sudo apt install python3.10-venv``. A folder called ``snooz_310_env`` should be created under the "snooz_workspace" folder. .. _activate_venv: To activate the virtual environment -------------------------------------- Activate the virtual environment in the Terminal, Command Prompt or PowerShell: * For Windows (CMD): ``call /path_to_virtual_environment/snooz_310_env/Scripts/activate.bat`` * For Windows (PowerShell or the VS Code terminal) : ``/path_to_virtual_environment/snooz_310_env/Scripts/Activate.ps1`` * For macOS (Terminal) : ``source /path_to_virtual_environment/snooz_310_env/bin/activate`` * For Linux (Terminal) : ``source /path_to_virtual_environment/snooz_310_env/bin/activate`` Once activated, you should see the name of the virtual environment in parenthesis in the terminal. To complete the setup of your virtual environment, install the external libraries required to run Snooz. The ``requirements.txt`` file is saved in the root folder of the "snooz-toolbox" repository you cloned previously. To install the requirements, type in the terminal or Command Prompt: | ``pip install -r requirements.txt`` .. warning:: To enable running PowerShell scripts on Windows, you need to change the execution policy. Run this command in PowerShell (no administrator rights required): ``Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`` Visual Studio Code as IDE ======================================= An Integrated Development Environment (IDE) is a software application that combines a source code editor, compiler/interpreter, debugger, and version control integration to streamline the development process within a single interface. We use Visual Studio Code (VS Code) as our IDE. It's a free tool developed by Microsoft and is compatible with multiple platforms, including Windows, Linux, and macOS. For installation instructions, please refer to the following link: https://code.visualstudio.com/download. Install the Python extension ------------------------------ VS Code is used for all kinds of programming tasks. To work with Python, you need to install a few extensions. * Open VS Code * From the navigation bar on the left, navigate to the extension panel(Ctrl-Shift-X). * Install "Python" extension from Microsoft. * Install "Qt for Python" : this extension is required to edit ``.ui`` files in Qt Designer and compile them into Python code. Configure your workspace ---------------------------- **Python Interpreter** Define the Python intepreter from the virtual environment ``snooz_310_env``. * Open VS Code * Navigate to File-> Open workspace from file * Choose the file snooz.code-workspace from the "snooz-toolbox" repository you cloned. * Navigate to View -> Command Palette (Ctrl-Shift-p) - Select "Python:Select Interpreter" - Select "Select at workspace level" - Find and select the Python executable within the folder of the Python virtual environment ``snooz_310_env`` you created in the previous step. .. note:: The path to the Python interpreter * Windows : "/snooz_310_env/Scripts/python"; * Linux and macOS : "snooz_310_env/bin/python" .. warning:: You may need to add the path to Python in the settings or the snooz.code-workspace file (when you virtual env does not appear in the selection.) * Open Visual Studio Code * Open snooz.code-workspace * Add the following setting : { // macOS and linux "python.defaultInterpreterPath": "/path_to_virtual_environment/snooz_310_env/bin/python" // windows "python.defaultInterpreterPath": "C:/path_to_virtual_environment/snooz_310_env/Scripts/python.exe" } An example of a ``snooz.code-workspace`` file with the ``python.defaultInterpreterPath`` defined. .. code-block:: json { "folders": [ { "path": "." } ], "settings": { "python.defaultInterpreterPath": "C:/Users/klacourse/Documents/snooz_workspace/snooz_310_env/Scripts/python.exe", "python.analysis.extraPaths": ["./src/main/python/"], "editor.rulers": [80], "python.terminal.activateEnvironment": true, "qtForPython.rcc.liveExecution.enabled": false, "qtForPython.uic.liveExecution.enabled": false, "qtForPython.qmlls.enabled": false, "qtForPython.uic.options": [ "-o", "${resourceDirname}${pathSeparator}${resourceBasenameNoExtension}.py" ] } } Run Snooz ======================================= To run Snooz from the source code see : :ref:`run_snooz` .. toctree::