pckg-install-local
==================

The ``pckg-install-local`` script is a Python utility that enables local installation and testing of Arduino core packages during development.

It allows to install an Arduino core without publishing it to a remote repository, from a local directory. 
The `arduino-cli` can only install cores which are hosted in a remote server.
In CI/CD this is convenient for two use cases:

- Working with the commit triggering the CI/CD pipeline for an Arduino core.
- Prevent the CI/CD downloads to increase the download statistics of the core package by installing it from a published release, which will skew the real user download statistics.

Overview
--------

When developing an Arduino core, you typically need to test your changes before publishing. This script automates the process of:

1. Starting a local HTTP server to host your package files (as arduino-cli cannot install from a local directory)
2. Creating a modified package index file with local URLs
3. Uninstalling any existing version of the core
4. Installing the core from your local development files
5. Cleaning up temporary files

This tool can be used for cores generated by the :doc:`arduino-packager` tool.

Features
--------

- **Local HTTP server**: Automatically starts a local server on a random port (8000-8200 range)
- **Package index modification**: Creates a local version of your package index with localhost URLs
- **Clean installation**: Removes existing installations and staging files before installing
- **Arduino CLI integration**: Uses Arduino CLI commands for proper core management
- **Verbose logging**: Optional detailed output for debugging
- **Cross-platform support**: Works on Linux, macOS, and Windows

Usage
-----

Basic usage:

.. code:: bash

    python pckg-install-local.py

With options:

.. code:: bash

    python pckg-install-local.py --pckg-dir /path/to/package --verbose

Command line options
^^^^^^^^^^^^^^^^^^^^

``--pckg-dir <directory>``
    Path to the package directory containing the Arduino core package files.
    
    **Default**: Current working directory
    
    **Example**: ``--pckg-dir ./build/``

``--verbose``
    Enable verbose logging output to see detailed information about the installation process.
    
    **Example**: ``--verbose``

``-v, --version``
    Display the version of the pckg-install-local tool.
    
    **Example**: ``--version``

Package directory structure
---------------------------

The package directory must contain:

1. **Package index file**: A ``.json`` file (e.g., ``package_mycore_index.json``)
2. **Core archive**: A ``.zip`` file containing the Arduino core (e.g., ``arduino-core-mycore-1.0.0.zip``)

Example directory structure:

.. code:: text

    package/
    ├── package_mycore_index.json       # Package index manifest
    └── arduino-core-mycore-1.0.0.zip   # Arduino core archive

Installation process
--------------------

The script performs the following steps:

1. **Server setup**
   
   - Starts a local HTTP server on a random port (8000-8200)
   - Serves files from the specified package directory

2. **Package index modification**
   
   - Locates the package index JSON file in the directory
   - Creates a local copy with ``_local`` suffix (e.g., ``package_mycore_index_local.json``)
   - Updates the package URL to point to the local server

3. **Core cleanup**
   
   - Uninstalls any existing version of the core using ``arduino-cli core uninstall``
   - Removes staging files from Arduino's installation directory
   - Cleans up previous local package index files

4. **Core installation**
   
   - Updates Arduino CLI core index
   - Installs the core using the local package index URL
   - Lists installed cores to verify installation

Prerequisites
-------------

- **Python 3.x** installed on your system
- **Arduino CLI** installed and available in your system PATH
- **Package files** generated by the arduino-packager tool or manually created
- **Network access** for Arduino CLI to update its index (internet connection)

.. note::
    The script requires Arduino CLI to be properly installed and configured. You can install it using the :doc:`arduino-cli-install` script.

Examples
--------

**Install from current directory:**

.. code:: bash

    python pckg-install-local.py

**Install with verbose output:**

.. code:: bash

    python pckg-install-local.py --verbose

**Install from specific package directory:**

.. code:: bash

    python pckg-install-local.py --pckg-dir ./build/package --verbose

**Check version:**

.. code:: bash

    python pckg-install-local.py --version

Troubleshooting
---------------

**"Package index file not found" error:**
    Ensure your package directory contains a ``.json`` file (package index manifest).

**"Package archive file not found" error:**
    Ensure your package directory contains a ``.zip`` file (Arduino core archive).

**"Server could not start" error:**
    The script tries random ports between 8000-8200. If all ports are busy, try closing other applications or restart your system.

**Arduino CLI command fails:**
    Verify that Arduino CLI is properly installed and accessible from the command line:
    
    .. code:: bash
    
        arduino-cli version

**Core installation fails:**
    Check that your package index file is valid JSON and contains the required Arduino core package structure.

.. warning::
    This script modifies Arduino CLI's core installations. Make sure to backup any important Arduino configurations before running it.

.. tip::
    Use the ``--verbose`` flag to see detailed logging output when troubleshooting installation issues.