build: Initialize Python virtual environment and install project dependencies.

.venv/lib/python3.11/site-packages/platformio/debug/process/__init__.py

@@ -0,0 +1,13 @@
+# Copyright (c) 2014-present PlatformIO <contact@platformio.org>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

.venv/lib/python3.11/site-packages/platformio/debug/process/base.py

@@ -0,0 +1,154 @@
+# Copyright (c) 2014-present PlatformIO <contact@platformio.org>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import asyncio
+import signal
+import subprocess
+import sys
+import time
+
+from platformio.compat import (
+    IS_WINDOWS,
+    aio_create_task,
+    aio_get_running_loop,
+    get_locale_encoding,
+)
+
+
+class DebugSubprocessProtocol(asyncio.SubprocessProtocol):
+    def __init__(self, factory):
+        self.factory = factory
+        self._is_exited = False
+
+    def connection_made(self, transport):
+        self.factory.connection_made(transport)
+
+    def pipe_data_received(self, fd, data):
+        pipe_to_cb = [
+            self.factory.stdin_data_received,
+            self.factory.stdout_data_received,
+            self.factory.stderr_data_received,
+        ]
+        pipe_to_cb[fd](data)
+
+    def connection_lost(self, exc):
+        self.process_exited()
+
+    def process_exited(self):
+        if self._is_exited:
+            return
+        self.factory.process_exited()
+        self._is_exited = True
+
+
+class DebugBaseProcess:
+    STDOUT_CHUNK_SIZE = 2048
+    LOG_FILE = None
+
+    def __init__(self):
+        self.transport = None
+        self._is_running = False
+        self._last_activity = 0
+        self._exit_future = None
+        self._stdin_read_task = None
+        self._std_encoding = get_locale_encoding()
+
+    async def spawn(self, *args, **kwargs):
+        wait_until_exit = False
+        if "wait_until_exit" in kwargs:
+            wait_until_exit = kwargs["wait_until_exit"]
+            del kwargs["wait_until_exit"]
+        for pipe in ("stdin", "stdout", "stderr"):
+            if pipe not in kwargs:
+                kwargs[pipe] = subprocess.PIPE
+        loop = aio_get_running_loop()
+        await loop.subprocess_exec(
+            lambda: DebugSubprocessProtocol(self), *args, **kwargs
+        )
+        if wait_until_exit:
+            self._exit_future = loop.create_future()
+            await self._exit_future
+
+    def is_running(self):
+        return self._is_running
+
+    def connection_made(self, transport):
+        self._is_running = True
+        self.transport = transport
+
+    def connect_stdin_pipe(self):
+        self._stdin_read_task = aio_create_task(self._read_stdin_pipe())
+
+    async def _read_stdin_pipe(self):
+        loop = aio_get_running_loop()
+        if IS_WINDOWS:
+            while True:
+                self.stdin_data_received(
+                    await loop.run_in_executor(None, sys.stdin.buffer.readline)
+                )
+        else:
+            reader = asyncio.StreamReader()
+            protocol = asyncio.StreamReaderProtocol(reader)
+            await loop.connect_read_pipe(lambda: protocol, sys.stdin)
+            while True:
+                self.stdin_data_received(await reader.readline())
+
+    def stdin_data_received(self, data):
+        self._last_activity = time.time()
+        if self.LOG_FILE:
+            with open(self.LOG_FILE, "ab") as fp:
+                fp.write(data)
+
+    def stdout_data_received(self, data):
+        self._last_activity = time.time()
+        if self.LOG_FILE:
+            with open(self.LOG_FILE, "ab") as fp:
+                fp.write(data)
+        while data:
+            chunk = data[: self.STDOUT_CHUNK_SIZE]
+            print(chunk.decode(self._std_encoding, "replace"), end="", flush=True)
+            data = data[self.STDOUT_CHUNK_SIZE :]
+
+    def stderr_data_received(self, data):
+        self._last_activity = time.time()
+        if self.LOG_FILE:
+            with open(self.LOG_FILE, "ab") as fp:
+                fp.write(data)
+        print(
+            data.decode(self._std_encoding, "replace"),
+            end="",
+            file=sys.stderr,
+            flush=True,
+        )
+
+    def process_exited(self):
+        self._is_running = False
+        self._last_activity = time.time()
+        # Allow terminating via SIGINT/CTRL+C
+        signal.signal(signal.SIGINT, signal.default_int_handler)
+        if self._stdin_read_task:
+            self._stdin_read_task.cancel()
+            self._stdin_read_task = None
+        if self._exit_future:
+            self._exit_future.set_result(True)
+            self._exit_future = None
+
+    def terminate(self):
+        if not self.is_running() or not self.transport:
+            return
+        try:
+            self.transport.kill()
+            self.transport.close()
+        except:  # pylint: disable=bare-except
+            pass

.venv/lib/python3.11/site-packages/platformio/debug/process/client.py

@@ -0,0 +1,104 @@
+# Copyright (c) 2014-present PlatformIO <contact@platformio.org>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import hashlib
+import os
+import signal
+import tempfile
+
+from platformio import fs, proc
+from platformio.cache import ContentCache
+from platformio.compat import IS_WINDOWS, hashlib_encode_data
+from platformio.debug.process.base import DebugBaseProcess
+from platformio.debug.process.server import DebugServerProcess
+from platformio.project.helpers import get_project_cache_dir
+
+
+class DebugClientProcess(DebugBaseProcess):
+    def __init__(self, project_dir, debug_config):
+        super().__init__()
+        self.project_dir = project_dir
+        self.debug_config = debug_config
+
+        self._server_process = None
+        self._session_id = None
+
+        if not os.path.isdir(get_project_cache_dir()):
+            os.makedirs(get_project_cache_dir())
+        self.working_dir = tempfile.mkdtemp(
+            dir=get_project_cache_dir(), prefix=".piodebug-"
+        )
+
+        self._target_is_running = False
+        self._errors_buffer = b""
+
+    async def run(self):
+        session_hash = (
+            self.debug_config.client_executable_path + self.debug_config.program_path
+        )
+        self._session_id = hashlib.sha1(hashlib_encode_data(session_hash)).hexdigest()
+        self._kill_previous_session()
+
+        if self.debug_config.server:
+            self._server_process = DebugServerProcess(self.debug_config)
+            self.debug_config.port = await self._server_process.run()
+
+    def connection_made(self, transport):
+        super().connection_made(transport)
+        self._lock_session(transport.get_pid())
+        # Disable SIGINT and allow GDB's Ctrl+C interrupt
+        signal.signal(signal.SIGINT, lambda *args, **kwargs: None)
+        self.connect_stdin_pipe()
+
+    def process_exited(self):
+        if self._server_process:
+            self._server_process.terminate()
+        super().process_exited()
+
+    def close(self):
+        self._unlock_session()
+        if self.working_dir and os.path.isdir(self.working_dir):
+            fs.rmtree(self.working_dir)
+
+    def __del__(self):
+        self.close()
+
+    def _kill_previous_session(self):
+        assert self._session_id
+        pid = None
+        with ContentCache() as cc:
+            pid = cc.get(self._session_id)
+            cc.delete(self._session_id)
+        if not pid:
+            return
+        if IS_WINDOWS:
+            kill = ["Taskkill", "/PID", pid, "/F"]
+        else:
+            kill = ["kill", pid]
+        try:
+            proc.exec_command(kill)
+        except:  # pylint: disable=bare-except
+            pass
+
+    def _lock_session(self, pid):
+        if not self._session_id:
+            return
+        with ContentCache() as cc:
+            cc.set(self._session_id, str(pid), "1h")
+
+    def _unlock_session(self):
+        if not self._session_id:
+            return
+        with ContentCache() as cc:
+            cc.delete(self._session_id)

.venv/lib/python3.11/site-packages/platformio/debug/process/gdb.py

@@ -0,0 +1,181 @@
+# Copyright (c) 2014-present PlatformIO <contact@platformio.org>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+import signal
+import time
+
+from platformio import telemetry
+from platformio.compat import aio_get_running_loop, is_bytes
+from platformio.debug import helpers
+from platformio.debug.exception import DebugInitError
+from platformio.debug.process.client import DebugClientProcess
+
+
+class GDBClientProcess(DebugClientProcess):
+    PIO_SRC_NAME = ".pioinit"
+    INIT_COMPLETED_BANNER = "PlatformIO: Initialization completed"
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._target_is_running = False
+        self._errors_buffer = b""
+
+    async def run(self, extra_args):  # pylint: disable=arguments-differ
+        await super().run()
+
+        self.generate_init_script(os.path.join(self.working_dir, self.PIO_SRC_NAME))
+        gdb_path = self.debug_config.client_executable_path or "gdb"
+        # start GDB client
+        args = [
+            gdb_path,
+            "-q",
+            "--directory",
+            self.working_dir,
+            "--directory",
+            self.project_dir,
+            "-l",
+            "10",
+        ]
+        args.extend(list(extra_args or []))
+        gdb_data_dir = self._get_data_dir(gdb_path)
+        if gdb_data_dir:
+            args.extend(["--data-directory", gdb_data_dir])
+        args.append(self.debug_config.program_path)
+
+        await self.spawn(*args, cwd=self.project_dir, wait_until_exit=True)
+
+    @staticmethod
+    def _get_data_dir(gdb_path):
+        if "msp430" in gdb_path:
+            return None
+        gdb_data_dir = os.path.abspath(
+            os.path.join(os.path.dirname(gdb_path), "..", "share", "gdb")
+        )
+        return gdb_data_dir if os.path.isdir(gdb_data_dir) else None
+
+    def generate_init_script(self, dst):
+        # default GDB init commands depending on debug tool
+        commands = self.debug_config.get_init_script("gdb").split("\n")
+
+        if self.debug_config.init_cmds:
+            commands = self.debug_config.init_cmds
+        commands.extend(self.debug_config.extra_cmds)
+
+        if not any("define pio_reset_run_target" in cmd for cmd in commands):
+            commands = [
+                "define pio_reset_run_target",
+                "   echo Warning! Undefined pio_reset_run_target command\\n",
+                "   monitor reset",
+                "end",
+            ] + commands
+        if not any("define pio_reset_halt_target" in cmd for cmd in commands):
+            commands = [
+                "define pio_reset_halt_target",
+                "   echo Warning! Undefined pio_reset_halt_target command\\n",
+                "   monitor reset halt",
+                "end",
+            ] + commands
+        if not any("define pio_restart_target" in cmd for cmd in commands):
+            commands += [
+                "define pio_restart_target",
+                "   pio_reset_halt_target",
+                "   $INIT_BREAK",
+                "   %s" % ("continue" if self.debug_config.init_break else "next"),
+                "end",
+            ]
+
+        banner = [
+            "echo PlatformIO Unified Debugger -> https://bit.ly/pio-debug\\n",
+            "echo PlatformIO: debug_tool = %s\\n" % self.debug_config.tool_name,
+            "echo PlatformIO: Initializing remote target...\\n",
+        ]
+        footer = ["echo %s\\n" % self.INIT_COMPLETED_BANNER]
+        commands = banner + commands + footer
+
+        with open(dst, mode="w", encoding="utf8") as fp:
+            fp.write("\n".join(self.debug_config.reveal_patterns(commands)))
+
+    def stdin_data_received(self, data):
+        super().stdin_data_received(data)
+        if b"-exec-run" in data:
+            if self._target_is_running:
+                token, _ = data.split(b"-", 1)
+                self.stdout_data_received(token + b"^running\n")
+                return
+            if self.debug_config.platform.is_embedded():
+                data = data.replace(b"-exec-run", b"-exec-continue")
+
+        if b"-exec-continue" in data:
+            self._target_is_running = True
+        if b"-gdb-exit" in data or data.strip() in (b"q", b"quit"):
+            # Allow terminating via SIGINT/CTRL+C
+            signal.signal(signal.SIGINT, signal.default_int_handler)
+            self.transport.get_pipe_transport(0).write(b"pio_reset_run_target\n")
+        self.transport.get_pipe_transport(0).write(data)
+
+    def stdout_data_received(self, data):
+        super().stdout_data_received(data)
+        self._handle_error(data)
+        # go to init break automatically
+        if self.INIT_COMPLETED_BANNER.encode() in data:
+            telemetry.log_debug_started(self.debug_config)
+            self._auto_exec_continue()
+
+    def console_log(self, msg):
+        if helpers.is_gdbmi_mode():
+            msg = helpers.escape_gdbmi_stream("~", msg)
+        self.stdout_data_received(msg if is_bytes(msg) else msg.encode())
+
+    def _auto_exec_continue(self):
+        auto_exec_delay = 0.5  # in seconds
+        if self._last_activity > (time.time() - auto_exec_delay):
+            aio_get_running_loop().call_later(0.1, self._auto_exec_continue)
+            return
+
+        if not self.debug_config.init_break or self._target_is_running:
+            return
+
+        self.console_log(
+            "PlatformIO: Resume the execution to `debug_init_break = %s`\n"
+            % self.debug_config.init_break
+        )
+        self.console_log(
+            "PlatformIO: More configuration options -> https://bit.ly/pio-debug\n"
+        )
+        if self.debug_config.platform.is_embedded():
+            self.transport.get_pipe_transport(0).write(
+                b"0-exec-continue\n" if helpers.is_gdbmi_mode() else b"continue\n"
+            )
+        else:
+            self.transport.get_pipe_transport(0).write(
+                b"0-exec-run\n" if helpers.is_gdbmi_mode() else b"run\n"
+            )
+        self._target_is_running = True
+
+    def stderr_data_received(self, data):
+        super().stderr_data_received(data)
+        self._handle_error(data)
+
+    def _handle_error(self, data):
+        self._errors_buffer = (self._errors_buffer + data)[-8192:]  # keep last 8 KBytes
+        if not (
+            self.PIO_SRC_NAME.encode() in self._errors_buffer
+            and b"Error in sourced" in self._errors_buffer
+        ):
+            return
+        telemetry.log_debug_exception(
+            DebugInitError(self._errors_buffer.decode()), self.debug_config
+        )
+        self.transport.close()

.venv/lib/python3.11/site-packages/platformio/debug/process/server.py

@@ -0,0 +1,149 @@
+# Copyright (c) 2014-present PlatformIO <contact@platformio.org>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import asyncio
+import os
+import re
+import time
+
+from platformio import fs
+from platformio.compat import IS_MACOS, IS_WINDOWS
+from platformio.debug.exception import DebugInvalidOptionsError
+from platformio.debug.helpers import escape_gdbmi_stream, is_gdbmi_mode
+from platformio.debug.process.base import DebugBaseProcess
+from platformio.proc import where_is_program
+
+
+class DebugServerProcess(DebugBaseProcess):
+    STD_BUFFER_SIZE = 1024
+
+    def __init__(self, debug_config):
+        super().__init__()
+        self.debug_config = debug_config
+        self._ready = False
+        self._std_buffer = {"out": b"", "err": b""}
+
+    async def run(self):  # pylint: disable=too-many-branches
+        server = self.debug_config.server
+        if not server:
+            return None
+        server_executable = server["executable"]
+        if not server_executable:
+            return None
+        if server["cwd"]:
+            server_executable = os.path.join(server["cwd"], server_executable)
+        if (
+            IS_WINDOWS
+            and not server_executable.endswith(".exe")
+            and os.path.isfile(server_executable + ".exe")
+        ):
+            server_executable = server_executable + ".exe"
+
+        if not os.path.isfile(server_executable):
+            server_executable = where_is_program(server_executable)
+        if not os.path.isfile(server_executable):
+            raise DebugInvalidOptionsError(
+                "Could not launch Debug Server '%s'. Please check that it "
+                "is installed and is included in a system PATH\n"
+                "See https://docs.platformio.org/page/plus/debugging.html"
+                % server_executable
+            )
+
+        openocd_pipe_allowed = all(
+            [
+                not self.debug_config.env_options.get(
+                    "debug_port", self.debug_config.tool_settings.get("port")
+                ),
+                "gdb" in self.debug_config.client_executable_path,
+                "openocd" in server_executable,
+            ]
+        )
+        if openocd_pipe_allowed:
+            args = []
+            if server["cwd"]:
+                args.extend(["-s", server["cwd"]])
+            args.extend(
+                ["-c", "gdb_port pipe; tcl_port disabled; telnet_port disabled"]
+            )
+            args.extend(server["arguments"])
+            str_args = " ".join(
+                [arg if arg.startswith("-") else '"%s"' % arg for arg in args]
+            )
+            return fs.to_unix_path('| "%s" %s' % (server_executable, str_args))
+
+        env = os.environ.copy()
+        # prepend server "lib" folder to LD path
+        if (
+            not IS_WINDOWS
+            and server["cwd"]
+            and os.path.isdir(os.path.join(server["cwd"], "lib"))
+        ):
+            ld_key = "DYLD_LIBRARY_PATH" if IS_MACOS else "LD_LIBRARY_PATH"
+            env[ld_key] = os.path.join(server["cwd"], "lib")
+            if os.environ.get(ld_key):
+                env[ld_key] = "%s:%s" % (env[ld_key], os.environ.get(ld_key))
+        # prepend BIN to PATH
+        if server["cwd"] and os.path.isdir(os.path.join(server["cwd"], "bin")):
+            env["PATH"] = "%s%s%s" % (
+                os.path.join(server["cwd"], "bin"),
+                os.pathsep,
+                os.environ.get("PATH", os.environ.get("Path", "")),
+            )
+
+        await self.spawn(
+            *([server_executable] + server["arguments"]), cwd=server["cwd"], env=env
+        )
+        await self._wait_until_ready()
+
+        return self.debug_config.port
+
+    async def _wait_until_ready(self):
+        ready_pattern = self.debug_config.server_ready_pattern
+        timeout = 60 if ready_pattern else 10
+        elapsed = 0
+        delay = 0.5
+        auto_ready_delay = 0.5
+        while not self._ready and self.is_running() and elapsed < timeout:
+            await asyncio.sleep(delay)
+            if not ready_pattern:
+                self._ready = self._last_activity < (time.time() - auto_ready_delay)
+            elapsed += delay
+
+    def _check_ready_by_pattern(self, data):
+        if self._ready:
+            return self._ready
+        ready_pattern = self.debug_config.server_ready_pattern
+        if ready_pattern:
+            if ready_pattern.startswith("^"):
+                self._ready = re.match(
+                    ready_pattern,
+                    data.decode("utf-8", "ignore"),
+                )
+            else:
+                self._ready = ready_pattern.encode() in data
+        return self._ready
+
+    def stdout_data_received(self, data):
+        super().stdout_data_received(
+            escape_gdbmi_stream("@", data) if is_gdbmi_mode() else data
+        )
+        self._std_buffer["out"] += data
+        self._check_ready_by_pattern(self._std_buffer["out"])
+        self._std_buffer["out"] = self._std_buffer["out"][-1 * self.STD_BUFFER_SIZE :]
+
+    def stderr_data_received(self, data):
+        super().stderr_data_received(data)
+        self._std_buffer["err"] += data
+        self._check_ready_by_pattern(self._std_buffer["err"])
+        self._std_buffer["err"] = self._std_buffer["err"][-1 * self.STD_BUFFER_SIZE :]