This change allows users to define custom resource files by placing a…

… resource file of the same name in their project directory. Currently it is enabled only for boards.json and fpga.json but can easily be enabled for other resources.

This way, users can use their own custom board without having to burden the stock resource files with niche boards.

The bulk of the change here is making the project dir known in resources.py when the resoruces are loaded.

If a custom resource file is used, an info message is printed to facilitate in supporting users.

DEVELOPER.md

@@ -0,0 +1,44 @@
+# APIO Developers Hints
+
+This file is not intended for APIO users.
+
+## Pre commit tests
+Before submitting a new commit, make sure the following commands runs successfuly (in the repository root):
+
+```shell
+make lint
+make tox
+```
+
+## Running an individual APIO test
+
+Run from the repo root. Replace with the path to the desire test.
+
+```shell
+test/code_commands/test_build.py
+```
+
+## Running APIO in a debugger
+
+Set the debugger to run the ``apio_run.py`` main with the regular ``apio`` arguments. Set the project directory ot the project file or use the ``--project_dir`` apio argument to point to the project directory.
+
+Example of an equivalent manual command:
+```
+python apio_run.py build --project_dir ~/projects/fpga/repo/hdl
+```
+
+## Running APIO commands using a dev repo
+
+One way is to link the pip package to the dev repository. Something along these lines. Adjust patches to match your system. The ``pip show`` command shows the directory where the stock pip package is installed.
+
+NOTE: This make the command ``apio init --scons`` opsolete since the scons files can be edited in the dev repository.
+
+```
+pip install apio
+pip show apio
+cd /Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages
+mv apio apio.original
+ln -s ~/projects/apio_dev/repo/apio
+```
+
+

apio/__main__.py

@@ -29,7 +29,7 @@ def __init__(self, *args, **kwargs):
         # -- Ex. /home/obijuan/Develop/(...)/apio/commands
         # -- Every apio command (Ex. apio build, apio upload...) is a
         # -- separate .py file located in the commands folder
-        self.commands_folder = util.get_full_path("commands")
+        self.commands_folder = util.get_apio_full_path("commands")
 
         self._cls = [None]
         super().__init__(*args, **kwargs)

apio/commands/boards.py

@@ -7,6 +7,7 @@
 # -- Licence GPLv2
 """Main implementation of APIO BOARDS command"""
 
+from pathlib import Path
 import click
 from apio.resources import Resources
 from apio import util
@@ -15,12 +16,20 @@
 # -- CONSTANTS
 # ------------------
 CMD = "boards"  # -- Comand name
+PROJECT_DIR = "project_dir"  # -- Option
 LIST = "list"  # -- Option
 FPGA = "fpga"  # -- Option
 
 
 @click.command(CMD, context_settings=util.context_settings())
 @click.pass_context
+@click.option(
+    "-p",
+    "--project-dir",
+    type=Path,
+    metavar="str",
+    help="Set the target directory for the project.",
+)
 @click.option(
     "-l",
     f"--{LIST}",
@@ -34,11 +43,12 @@ def cli(ctx, **kwargs):
     """Manage FPGA boards."""
 
     # -- Extract the arguments
+    project_dir = kwargs[PROJECT_DIR]  # -- str
     _list = kwargs[LIST]  # -- bool
     fpga = kwargs[FPGA]  # -- bool
 
     # -- Access to the apio resources
-    resources = Resources()
+    resources = Resources(project_dir=project_dir)
 
     # -- Option 1: List boards
     if _list:

apio/commands/init.py

@@ -67,26 +67,26 @@ def cli(ctx, **kwargs):
     top_module = kwargs[TOP_MODULE]
 
     # -- Create a project
-    project = Project()
+    project = Project(project_dir)
 
     # -- scons option: Create default SConstruct file
     if scons:
-        project.create_sconstruct(project_dir, "ice40", sayyes)
+        project.create_sconstruct("ice40", sayyes)
 
-    # -- Create the apio.ini file
+    # -- Create the project file apio.ini
     elif board:
         # -- Set the default top_module when creating the ini file
         if not top_module:
             top_module = "main"
 
         # -- Create the apio.ini file
-        project.create_ini(board, top_module, project_dir, sayyes)
+        project.create_ini(board, top_module, sayyes)
 
     # -- Add the top_module to the apio.ini file
     elif top_module:
 
         # -- Update the apio.ini file
-        project.update_ini(top_module, project_dir)
+        project.update_ini(top_module)
 
     # -- No options: show help
     else:

apio/commands/install.py

@@ -7,6 +7,7 @@
 # -- Licence GPLv2
 """Main implementation of APIO INSTALL command"""
 
+from pathlib import Path
 import click
 from apio.managers.installer import Installer, list_packages
 from apio.resources import Resources
@@ -16,14 +17,17 @@
 # -- CONSTANTS
 # ------------------
 CMD = "install"  # -- Comand name
+PROJECT_DIR = "project_dir"  # -- Option
 PACKAGES = "packages"  # -- Argument
 ALL = "all"  # -- Option
 LIST = "list"  # -- Option
 FORCE = "force"  # -- Option
 PLATFORM = "platform"  # -- Option
 
 
-def install_packages(packages: list, platform: str, force: bool):
+def install_packages(
+    packages: list, platform: str, resources: Resources, force: bool
+):
     """Install the apio packages passed as a list
     * INPUTS:
       - packages: List of packages (Ex. ['examples', 'oss-cad-suite'])
@@ -34,15 +38,23 @@ def install_packages(packages: list, platform: str, force: bool):
     for package in packages:
 
         # -- The instalation is performed by the Installer object
-        inst = Installer(package, platform, force)
+        modifiers = Installer.Modifiers(force=force, checkversion=True)
+        installer = Installer(package, platform, resources, modifiers)
 
         # -- Install the package!
-        inst.install()
+        installer.install()
 
 
 @click.command(CMD, context_settings=util.context_settings())
 @click.pass_context
 @click.argument(PACKAGES, nargs=-1)
+@click.option(
+    "-p",
+    "--project-dir",
+    type=Path,
+    metavar="str",
+    help="Set the target directory for the project.",
+)
 @click.option("-a", f"--{ALL}", is_flag=True, help="Install all packages.")
 @click.option(
     "-l", f"--{LIST}", is_flag=True, help="List all available packages."
@@ -64,23 +76,23 @@ def cli(ctx, **kwargs):
 
     # -- Extract the arguments
     packages = kwargs[PACKAGES]  # -- tuple
+    project_dir = kwargs[PROJECT_DIR]  # -- str
     platform = kwargs[PLATFORM]  # -- str
     _all = kwargs[ALL]  # -- bool
     _list = kwargs[LIST]  # -- bool
     force = kwargs[FORCE]  # -- bool
 
+    # -- Load the resources.
+    resources = Resources(platform=platform, project_dir=project_dir)
+
     # -- Install the given apio packages
     if packages:
-        install_packages(packages, platform, force)
+        install_packages(packages, platform, resources, force)
 
     # -- Install all the available packages (if any)
     elif _all:
-
-        # -- Get all the resources
-        resources = Resources(platform)
-
         # -- Install all the available packages for this platform!
-        install_packages(resources.packages, platform, force)
+        install_packages(resources.packages, platform, resources, force)
 
     # -- List all the packages (installed or not)
     elif _list:

apio/commands/system.py

@@ -7,15 +7,19 @@
 # -- Licence GPLv2
 """Main implementation of APIO SYSTEM command"""
 
+from pathlib import Path
 import click
 from apio import util
 from apio.util import get_systype
 from apio.managers.system import System
+from apio.resources import Resources
+
 
 # ------------------
 # -- CONSTANTS
 # ------------------
 CMD = "system"  # -- Comand name
+PROJECT_DIR = "project_dir"  # -- Option
 LSFTDI = "lsftdi"  # -- Option
 LSUSB = "lsusb"  # -- Option
 LSSERIAL = "lsserial"  # -- Option
@@ -24,6 +28,13 @@
 
 @click.command(CMD, context_settings=util.context_settings())
 @click.pass_context
+@click.option(
+    "-p",
+    "--project-dir",
+    type=Path,
+    metavar="str",
+    help="Set the target directory for the project.",
+)
 @click.option(
     f"--{LSFTDI}", is_flag=True, help="List all connected FTDI devices."
 )
@@ -39,13 +50,17 @@ def cli(ctx, **kwargs):
     """System tools."""
 
     # -- Extract the arguments
+    project_dir = kwargs[PROJECT_DIR]
     lsftdi = kwargs[LSFTDI]
     lsusb = kwargs[LSUSB]
     lsserial = kwargs[LSSERIAL]
     info = kwargs[INFO]
 
+    # Load the various resource files.
+    resources = Resources(project_dir=project_dir)
+
     # -- Create the system object
-    system = System()
+    system = System(resources)
 
     # -- List all connected ftdi devices
     if lsftdi:

apio/commands/uninstall.py

@@ -7,22 +7,26 @@
 # -- Licence GPLv2
 """Main implementation of APIO UNINSTALL command"""
 
+from pathlib import Path
 import click
 from apio.managers.installer import Installer, list_packages
 from apio.profile import Profile
 from apio import util
+from apio.resources import Resources
+
 
 # ------------------
 # -- CONSTANTS
 # ------------------
 CMD = "uninstall"  # -- Comand name
+PROJECT_DIR = "project_dir"  # -- Option
 PACKAGES = "packages"  # -- Argument
 ALL = "all"  # -- Option
 LIST = "list"  # -- Option
 PLATFORM = "platform"  # -- Option
 
 
-def _uninstall(packages: list, platform: str):
+def _uninstall(packages: list, platform: str, resources: Resources):
     """Uninstall the given list of packages"""
 
     # -- Ask the user for confirmation
@@ -32,10 +36,11 @@ def _uninstall(packages: list, platform: str):
         for package in packages:
 
             # -- The uninstalation is performed by the Installer object
-            inst = Installer(package, platform, checkversion=False)
+            modifiers = Installer.Modifiers(force=False, checkversion=False)
+            installer = Installer(package, platform, resources, modifiers)
 
             # -- Uninstall the package!
-            inst.uninstall()
+            installer.uninstall()
 
     # -- User quit!
     else:
@@ -45,6 +50,13 @@ def _uninstall(packages: list, platform: str):
 @click.command(CMD, context_settings=util.context_settings())
 @click.pass_context
 @click.argument(PACKAGES, nargs=-1)
+@click.option(
+    "-p",
+    "--project-dir",
+    type=Path,
+    metavar="str",
+    help="Set the target directory for the project.",
+)
 @click.option("-a", f"--{ALL}", is_flag=True, help="Uninstall all packages.")
 @click.option(
     "-l", f"--{LIST}", is_flag=True, help="List all installed packages."
@@ -66,10 +78,14 @@ def cli(ctx, **kwargs):
     platform = kwargs[PLATFORM]  # -- str
     _all = kwargs[ALL]  # -- bool
     _list = kwargs[LIST]  # -- bool
+    project_dir = kwargs[PROJECT_DIR]  # -- str
+
+    # -- Load the resources.
+    resources = Resources(platform=platform, project_dir=project_dir)
 
     # -- Uninstall the given apio packages
     if packages:
-        _uninstall(packages, platform)
+        _uninstall(packages, platform, resources)
 
     # -- Uninstall all the packages
     elif _all:
@@ -78,7 +94,7 @@ def cli(ctx, **kwargs):
         packages = Profile().packages
 
         # -- Uninstall them!
-        _uninstall(packages, platform)
+        _uninstall(packages, platform, resources)
 
     # -- List all the packages (installed or not)
     elif _list: