diff --git a/.gitignore b/.gitignore index c8acd158b..e4cbf0d80 100644 --- a/.gitignore +++ b/.gitignore @@ -11,5 +11,6 @@ git_hash.txt /.coverage venv/ +.venv/ test.txt test.xml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0989e2256..1589c0eee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,25 +14,94 @@ Possible ways you can help: * Reviewing [existing pull requests](https://github.com/ArduPilot/MethodicConfigurator/pulls), and notifying the maintainer if it passes your code review. * Finding and fixing [security issues](SECURITY.md) -Get the code with: +## Learning the Code -```bash -git clone https://github.com/ArduPilot/MethodicConfigurator.git -cd MethodicConfigurator -``` - -and read [our architecture](https://ardupilot.github.io/MethodicConfigurator/ARCHITECTURE.html) to get a better understanding of the project. +Read [our architecture](https://ardupilot.github.io/MethodicConfigurator/ARCHITECTURE.html) to get a better understanding of the project. and also: * [System requirements](https://ardupilot.github.io/MethodicConfigurator/SYSTEM_REQUIREMENTS.html) * [Compliance](https://ardupilot.github.io/MethodicConfigurator/COMPLIANCE.html) +## Setting up developer environment + +1. [Install git](https://git-scm.com/install/) on your computer. +2. Create a free [personal github account](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github) +3. [Log in to your github account](https://github.com/login) using a browser +4. [Fork the ArduPilot/MethodicConfigurator github repository](https://github.com/ArduPilot/MethodicConfigurator/fork). +5. Clone your fork and navigate into it: + + ```bash + git clone https://github.com/YOUR_USER_NAME/MethodicConfigurator.git + cd MethodicConfigurator + ``` + +6. Run the following helper scripts: + + On Windows: + + ```powershell + .\SetupDeveloperPC.bat + ``` + + On Linux and macOS: + + ```bash + ./SetupDeveloperPC.sh + ``` + +The above scripts will: + +* Configure Git and useful aliases +* Create a Python virtual environment and install project dependencies +* Install recommended VSCode extensions +* Set up pre-commit hooks for linting and formatting +* Install GNU gettext tools for internationalization support + +## Executing the code + +You can either install the Methodic Configurator as a package or run it locally from your development codebase. +Installing the package will fetch the latest stable release version — see the [installation guide](https://ardupilot.github.io/MethodicConfigurator/INSTALL.html) for details. + +To run it locally (from your cloned repository): + +On Windows: + +```powershell +.venv\Scripts\activate.ps1 +python3 -m ardupilot_methodic_configurator +``` + +On macOS & Linux: + +```bash +source .venv/bin/activate +python3 -m ardupilot_methodic_configurator +``` + +More detailed usage instructions can be found in our [user manual](https://ardupilot.github.io/MethodicConfigurator/USERMANUAL) + ## Submitting patches -Please see our [wiki article](https://ardupilot.org/dev/docs/submitting-patches-back-to-master.html). +Follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) style for your git commit messages. + +Each commit should be signed off using the `--signoff` option in `git commit`. +By signing off your commit, you certify that you agree to the terms of the [Developer Certificate of Origin (DCO)](https://developercertificate.org/). + +You can sign by either your commit by pressing the *sign-off* button on `git gui` or by using the command line: + +```bash +# Sign off a commit as you're making it +git commit --signoff -m "commit message" + +# Add a signoff to the last commit you made +git commit --amend --signoff + +# Rebase your branch against master and sign off every commit in your branch +git rebase --signoff master +``` -To contribute, you can send a [pull request on GitHub](https://github.com/ArduPilot/MethodicConfigurator/pulls). +Once your changes are ready, submit a [GitHub Pull Request (PR)](https://github.com/ArduPilot/MethodicConfigurator/pulls). ## Development Team diff --git a/INSTALL.md b/INSTALL.md index 5e19774fc..a8fbce1ed 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -95,8 +95,8 @@ You need to create and activate a new virtual environment before you can run the sudo apt install python3-tk python -m venv .ardupilot_methodic_configurator_venv source .ardupilot_methodic_configurator_venv/bin/activate -python -m pip install --upgrade pip -pip install ardupilot_methodic_configurator +python -m pip install uv +uv pip install ardupilot_methodic_configurator ``` To run it, execute the command line: diff --git a/SetupDeveloperPC.bat b/SetupDeveloperPC.bat index d86e1767d..d1b4f4f19 100644 --- a/SetupDeveloperPC.bat +++ b/SetupDeveloperPC.bat @@ -1,6 +1,8 @@ @echo off setlocal enabledelayedexpansion +:: Configure a Microsoft Windows developer PC for ArduPilot Methodic Configurator development. + :: Store the original directory set "ORIGINAL_DIR=%CD%" @@ -48,11 +50,22 @@ if "!found!"=="0" ( :checkDone +:: Create a local virtual environment if it doesn't exist +if not exist ".venv" ( + echo Creating Python virtual environment... + python -m venv .venv +) + +:: Activate the virtual environment +echo Activating virtual environment... +call .venv\Scripts\activate.bat +call :InstallDependencies call :ConfigureArgComplete call :ConfigureGit call :ConfigureVSCode call :ConfigurePreCommit +call :InstallMsgfmt echo running pre-commit checks on all Files pre-commit run -a @@ -60,6 +73,22 @@ pre-commit run -a :: Change back to the original directory cd /d %ORIGINAL_DIR% +echo. +echo To run the ArduPilot methodic configurator GUI, execute the following commands: +echo. +echo .venv\Scripts\activate.ps1 +echo python3 -m ardupilot_methodic_configurator +echo. +echo If you encounter issues with auto-connecting to the wrong device on MS Windows, +echo you can explicitly set the device with the --device command line option: +echo. +echo python3 -m ardupilot_methodic_configurator --device COMX +echo. +echo Replace COMX with the correct COM port for your device. +echo. +echo For more detailed usage instructions, please refer to the USERMANUAL.md file. +echo. + echo Script completed successfully. exit /b @@ -85,7 +114,6 @@ git config --local alias.cm "commit -m" git config --local alias.pom "push origin master" git config --local alias.aa "add --all" git config --local alias.df diff -git config --local alias.su "submodule update --init --recursive" git config --local credential.helper manager git config --local pull.rebase true git config --local push.autoSetupRemote @@ -208,3 +236,14 @@ if !ERRORLEVEL! equ 0 ( ) goto :eof + +:InstallMsgfmt +echo Installing GNU gettext tools (msgfmt)... +call install_msgfmt.bat +goto :eof + +:InstallDependencies +echo Installing project dependencies... +python -m pip install uv +uv pip install -e .[dev] +goto :eof diff --git a/SetupDeveloperPC.sh b/SetupDeveloperPC.sh index 085e75c0c..8defa0362 100755 --- a/SetupDeveloperPC.sh +++ b/SetupDeveloperPC.sh @@ -1,5 +1,7 @@ #!/bin/bash # +# Configure a Linux or macOS developer PC for ArduPilot Methodic Configurator development. +# # SPDX-FileCopyrightText: 2024-2025 Amilcar do Carmo Lucas # # SPDX-License-Identifier: GPL-3.0-or-later @@ -21,24 +23,47 @@ ORIGINAL_DIR=$(pwd) # Change to the directory where the script resides cd "$(dirname "$0")" || exit +# Install macOS dependencies early if on macOS +if command -v brew &> /dev/null; then + echo "Installing macOS dependencies with Homebrew..." + brew install uv python-tk@3.9 + echo "Creating Python virtual environment with uv..." + uv venv --python 3.9 +else + # Create a local virtual environment if it doesn't exist + if [ ! -d ".venv" ]; then + echo "Creating Python virtual environment..." + python3 -m venv .venv + fi +fi + +# Activate the virtual environment +echo "Activating virtual environment..." +# shellcheck disable=SC1091 +source .venv/bin/activate + InstallDependencies() { echo "Updating package lists..." if command -v apt-get &> /dev/null; then sudo apt-get update # Install Python3 PIL.ImageTk for GUI support echo "Installing Python3 PIL.ImageTk..." - sudo apt-get install -y python3-pil.imagetk + sudo apt-get install -y python3-pil.imagetk gettext + python3 -m pip install uv + elif command -v brew &> /dev/null; then + echo "macOS dependencies already installed." else - echo "apt-get not found. Skipping system package updates." + echo "Neither apt-get nor brew found. Please install dependencies manually." fi + # No need to uninstall serial and pyserial anymore as the virtual environment is isolated # Uninstall serial and pyserial to avoid conflicts - echo "Uninstalling serial and pyserial..." - sudo python3 -m pip uninstall -y serial pyserial + # echo "Uninstalling serial and pyserial..." + # uv pip uninstall -y serial pyserial # Install the project dependencies echo "Installing project dependencies..." - python3 -m pip install -e .[dev] + uv pip install -e .[dev] } ConfigureGit() { @@ -63,7 +88,6 @@ ConfigureGit() { git config --local alias.pom "push origin master" git config --local alias.aa "add --all" git config --local alias.df diff - git config --local alias.su "submodule update --init --recursive" git config --local credential.helper manager git config --local pull.rebase true git config --local push.autoSetupRemote @@ -109,6 +133,24 @@ ConfigureVSCode() { exit 1 fi + echo "Installing code spellcheker extension..." + if ! code --install-extension streetsidesoftware.code-spell-checker; then + echo "Failed to install code spellcheker extension." + exit 1 + fi + + echo "Installing the Python VSCode extension..." + if ! code --install-extension ms-python.python; then + echo "Failed to install Python VSCode extension." + exit 1 + fi + + echo "Installing ruff extension..." + if ! code --install-extension charliermarsh.ruff; then + echo "Failed to install ruff extension." + exit 1 + fi + fi } @@ -128,5 +170,14 @@ pre-commit run -a # Change back to the original directory cd "$ORIGINAL_DIR" || exit +echo "" +echo "To run the ArduPilot methodic configurator GUI, execute the following commands:" +echo "" +echo "source .venv/bin/activate" +echo "python3 -m ardupilot_methodic_configurator" +echo "" +echo "For more detailed usage instructions, please refer to the USERMANUAL.md file." +echo "" + echo "Script completed successfully." exit 0 diff --git a/install_macos.sh b/install_macos.sh deleted file mode 100755 index 954100e66..000000000 --- a/install_macos.sh +++ /dev/null @@ -1,39 +0,0 @@ -#!/bin/bash -# -# SPDX-FileCopyrightText: 2024-2025 Amilcar do Carmo Lucas -# -# SPDX-License-Identifier: GPL-3.0-or-later - -# Use uv to create a virtual environment and replace python pip -# Install tkinter for Python 3.9 -brew install uv python-tk@3.9 - -# Use venv if you use python3 due to the PEP668 -uv venv --python 3.9 -# shellcheck source=/dev/null -source .venv/bin/activate - -# Uninstall serial and pyserial to avoid conflicts -echo "Uninstalling serial and pyserial..." -uv pip uninstall serial pyserial - -# Install the project dependencies -echo "Installing project dependencies..." -uv pip install -e .[dev] - -# configure git local repository settings -git config --local pull.rebase true -git config --local push.autoSetupRemote -git config --local init.defaultbranch master -git config --local sequence.editor "code --wait" - -# install pre-commit git hooks -pre-commit install - - -echo "Installation complete." -echo "" -echo "You can run the ArduPilot methodic configurator GUI by executing:" -echo "source .venv/bin/activate && python3 -m ardupilot_methodic_configurator" -echo "" -echo "For more detailed usage instructions, please refer to the USERMANUAL.md file." diff --git a/install_windows.bat b/install_windows.bat deleted file mode 100644 index 616662b96..000000000 --- a/install_windows.bat +++ /dev/null @@ -1,53 +0,0 @@ -@echo off -rem SPDX-FileCopyrightText: 2024-2025 Amilcar do Carmo Lucas -rem -rem SPDX-License-Identifier: GPL-3.0-or-later - -echo WARNING: This script should only be run by ArduPilot methodic configurator developers. -echo Normal users should use https://ardupilot.github.io/MethodicConfigurator/INSTALL.html instead. -choice /C YN /M "Do you want to proceed? (Y/N)" -if errorlevel 2 goto :skip_uninstall -if errorlevel 1 goto :do_install - -:do_install -rem Check if Python 3 is installed -where python3 >nul 2>&1 -if %errorlevel% neq 0 ( - echo ERROR: Python 3 is not installed or not in PATH. - echo Please install Python 3 and ensure it's in your system PATH. - pause - exit /b 1 -) - -echo WARNING: If you proceed the python serial package will be uninstalled because it conflicts with pyserial. -choice /C YN /M "Do you want to proceed? (Y/N)" -if errorlevel 2 goto :skip_uninstall -if errorlevel 1 goto :uninstall_python_serial - -:uninstall_python_serial -python3 -m pip uninstall serial pyserial -y -echo. -echo python serial has been successfully uninstalled. -echo. - -rem Install all dependencies defined in setup.py -python3 -m pip install -e .[dev] - -echo. -echo To run the ArduPilot methodic configurator GUI, execute the following command: -echo. -echo python3 -m ardupilot_methodic_configurator -echo. -echo If you encounter issues with auto-connecting to the wrong device on MS Windows, -echo you can explicitly set the device with the --device command line option: -echo. -echo python3 -m ardupilot_methodic_configurator --device COMX -echo. -echo Replace COMX with the correct COM port for your device. -echo. -echo For more detailed usage instructions, please refer to the USERMANUAL.md file. -goto :eof - -:skip_uninstall -echo Operation cancelled by the user. -goto :eof