pyflashgui 0.1.0__py3-none-any.whl

pyflashgui/core/updates.py

@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""Asking GitHub whether there is a newer release.
+
+This runs only when the user picks Help > Check for updates. pyflashgui makes
+no network connection of its own accord, and this one sends nothing about the
+machine it is on: it is an ordinary unauthenticated GET of a public API URL,
+and nothing is downloaded or installed -- a newer version just offers to open
+the releases page in a browser.
+
+Only the standard library is used, so no dependency is added for a feature
+that is used once in a while.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+
+REPO = "davhodg/pyflashgui"
+API = f"https://api.github.com/repos/{REPO}"
+RELEASES_API = f"{API}/releases/latest"
+RELEASES_PAGE = f"https://github.com/{REPO}/releases"
+PROJECT_PAGE = f"https://github.com/{REPO}"
+README_PAGE = f"{PROJECT_PAGE}#readme"
+COMMITS_PAGE = f"{PROJECT_PAGE}/commits"
+PYPI_API = "https://pypi.org/pypi/pyflashgui/json"
+PYPI_PAGE = "https://pypi.org/project/pyflashgui/"
+#: What a checkout on a branch GitHub has never heard of is compared against.
+DEFAULT_BRANCH = "master"
+SHORT = 7
+TIMEOUT_S = 6.0
+
+
+def parse_version(text: str) -> tuple[int, ...]:
+    """The numeric parts of a version, so "v1.2.0" and "1.2" compare sensibly.
+
+    Anything that is not a number is ignored rather than guessed at: a release
+    candidate suffix is not worth a version grammar of our own.
+    """
+    return tuple(int(part) for part in re.findall(r"\d+", text)) or (0,)
+
+
+def is_newer(candidate: str, current: str) -> bool:
+    """Whether ``candidate`` is a later version than ``current``.
+
+    A development build comes *before* the release it is numbered for:
+    0.1.0.dev5 is on its way to 0.1.0, so 0.1.0 is newer, although its
+    digits alone would say the opposite.
+    """
+
+    def key(text: str, length: int) -> tuple:
+        release, dev, number = text.lower().partition("dev")
+        parts = parse_version(release)
+        padded = parts + (0,) * (length - len(parts))  # 1.2 is not newer than 1.2.0
+        # A release sorts after every dev build of itself.
+        return padded, (0, *parse_version(number)) if dev else (1,)
+
+    length = max(len(parse_version(v.lower().partition("dev")[0])) for v in (candidate, current))
+    return key(candidate, length) > key(current, length)
+
+
+@dataclass
+class Release:
+    version: str
+    url: str
+    #: True for a version on PyPI, which is updated with pip rather than by
+    #: downloading anything.
+    pip: bool = False
+
+
+def _get(url: str, timeout: float) -> tuple[dict | None, int, str]:
+    """(payload, 200, "") or (None, status, problem): a 404 is left to the caller,
+    since what it means depends on what was asked.
+
+    Every failure is reported as text rather than raised: not being able to
+    reach GitHub is an ordinary thing to happen, not an error in pyflashgui.
+    """
+    request = urllib.request.Request(
+        url, headers={"Accept": "application/vnd.github+json", "User-Agent": "pyflashgui"}
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return json.load(response), 200, ""
+    except urllib.error.HTTPError as exc:
+        if exc.code == 403:
+            return None, 403, "GitHub declined the request (its rate limit). Try again later."
+        return None, exc.code, f"GitHub returned {exc.code} {exc.reason}."
+    except urllib.error.URLError as exc:
+        return None, 0, f"Could not reach GitHub: {exc.reason}"
+    except (TimeoutError, OSError) as exc:
+        return None, 0, f"Could not reach GitHub: {exc}"
+    except json.JSONDecodeError:
+        return None, 0, "GitHub's reply could not be read."
+
+
+def latest_release(timeout: float = TIMEOUT_S) -> tuple[Release | None, str]:
+    """Return (release, problem). Exactly one of the two is meaningful."""
+    payload, status, problem = _get(RELEASES_API, timeout)
+    if status == 404:
+        # Also what a private repository looks like from outside.
+        return None, "No releases have been published yet."
+    if payload is None:
+        return None, problem
+    tag = str(payload.get("tag_name") or "").strip()
+    if not tag:
+        return None, "GitHub reported a release with no version."
+    return Release(version=tag.lstrip("vV"), url=payload.get("html_url") or RELEASES_PAGE), ""
+
+
+def latest_on_pypi(timeout: float = TIMEOUT_S) -> tuple[Release | None, str]:
+    """Return (release, problem) for the newest version on PyPI.
+
+    For a pip installation: the release on GitHub is the Windows installer,
+    which is the wrong download for somebody who installed with pip.
+    """
+    payload, status, problem = _get(PYPI_API, timeout)
+    if status == 404:
+        return None, "pyflashgui is not on PyPI."
+    if payload is None:
+        return None, problem
+    version = str((payload.get("info") or {}).get("version") or "").strip()
+    if not version:
+        return None, "PyPI's reply could not be read."
+    return Release(version=version, url=f"{PYPI_PAGE}{version}/", pip=True), ""
+
+
+@dataclass
+class Standing:
+    """Where a source checkout is against the same branch on GitHub."""
+
+    branch: str
+    here: str  # this checkout's commit, short
+    latest: str  # GitHub's newest commit on the branch, short
+    behind: int = 0  # commits GitHub has that this checkout does not
+    ahead: int = 0  # commits here that GitHub does not have
+    #: False when GitHub has never seen this checkout's commit: one made here
+    #: and not pushed, or one from a fork.
+    known: bool = True
+
+    @property
+    def url(self) -> str:
+        return f"{COMMITS_PAGE}/{self.branch}"
+
+
+def checkout_standing(
+    branch: str | None, commit: str, timeout: float = TIMEOUT_S
+) -> tuple[Standing | None, str]:
+    """Return (standing, problem) for a checkout on this branch and commit.
+
+    A release says nothing to somebody running what they pulled: between two
+    releases every commit calls itself the same version. What they want to
+    know is whether there is more to pull.
+    """
+    branch = branch or DEFAULT_BRANCH
+    here = commit[:SHORT]
+
+    def tip(name: str) -> tuple[dict | None, int, str]:
+        return _get(f"{API}/commits/{urllib.parse.quote(name)}", timeout)
+
+    payload, status, problem = tip(branch)
+    if status in (404, 422) and branch != DEFAULT_BRANCH:
+        # A branch made here, which GitHub has not got: the main one is what
+        # there is to compare with.
+        branch = DEFAULT_BRANCH
+        payload, status, problem = tip(branch)
+    if payload is None:
+        return None, problem
+    latest = str(payload.get("sha") or "")
+    if not latest:
+        return None, "GitHub's reply could not be read."
+    if latest == commit:
+        return Standing(branch, here, latest[:SHORT]), ""
+
+    compared, status, problem = _get(f"{API}/compare/{commit}...{latest}", timeout)
+    if status in (404, 422):
+        return Standing(branch, here, latest[:SHORT], known=False), ""
+    if compared is None:
+        return None, problem
+    # Compared from here to GitHub's tip: what it is ahead by is what this
+    # checkout is behind by, and the other way about.
+    return (
+        Standing(
+            branch,
+            here,
+            latest[:SHORT],
+            behind=int(compared.get("ahead_by") or 0),
+            ahead=int(compared.get("behind_by") or 0),
+        ),
+        "",
+    )

pyflashgui/core/worker.py

@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""A queue-fed worker thread for blocking probe calls (connect, erase, program).
+
+Each job is a plain function; its result or exception is delivered back on the
+GUI thread through ``done``, so callers never block the window. One worker
+per probe keeps what is asked of it sequential, which is what a probe wants
+anyway.
+"""
+
+from __future__ import annotations
+
+import queue
+from collections.abc import Callable
+from typing import Any
+
+from PySide6.QtCore import QObject, QThread, Signal, Slot
+
+Callback = Callable[[Any, str | None], None]
+
+
+class Worker(QThread):
+    done = Signal(object)  # (callback, result, error)
+
+    def __init__(self, parent: QObject | None = None) -> None:
+        super().__init__(parent)
+        self._jobs: queue.Queue = queue.Queue()
+        self.done.connect(self._deliver)
+        #: Until it is stopped. Stopping twice must not disconnect twice,
+        #: which PySide complains about at length.
+        self._delivering = True
+
+    def submit(self, fn: Callable[[], Any], callback: Callback) -> None:
+        # Started on first use: a QThread that is running when Qt destroys it
+        # aborts the process, so an owner that is created and dropped without
+        # ever asking for anything must not leave a thread behind.
+        if not self.isRunning():
+            self.start()
+        self._jobs.put((fn, callback))
+
+    def run(self) -> None:
+        while (job := self._jobs.get()) is not None:
+            fn, callback = job
+            try:
+                self.done.emit((callback, fn(), None))
+            except Exception as exc:  # report, never die
+                self.done.emit((callback, None, f"{type(exc).__name__}: {exc}"))
+
+    @Slot(object)
+    def _deliver(self, packet: tuple) -> None:
+        callback, result, error = packet
+        callback(result, error)
+
+    def stop(self) -> None:
+        """Finish the queue and stop delivering results.
+
+        The ``done`` connection is dropped first: a queued result arriving
+        after the owner has been torn down would be delivered to a dead
+        object, which Qt punishes with an access violation rather than an
+        exception.
+        """
+        if self._delivering:
+            self._delivering = False
+            try:
+                self.done.disconnect(self._deliver)
+            except (RuntimeError, TypeError):  # the C++ side has already gone
+                pass
+        if not self.isRunning():
+            return
+        self._jobs.put(None)
+        self.wait(2000)

pyflashgui/core/workspaces.py

@@ -0,0 +1,250 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""Named workspaces: one per product, and one called ``default`` nobody need meet.
+
+A workspace is everything about *what you are working on*: the target, the
+probe and its speed, the files to program and the dock layout. One folder, so
+it can be copied, backed up or sent to someone else whole. What stays outside
+it is everything about *this machine*: where the window sits on the screen.
+
+The design constraint is that somebody with one product must never have to
+know the word exists. On first run there is a workspace called ``default``,
+created silently, and pyflashgui behaves exactly as it would with no
+workspaces at all. The name appears in the title bar only when it is *not* ``default``.
+
+There is no Save, and therefore no unsaved changes: a workspace saves
+continuously, which is what ``settings.json`` has always done. The whole
+surface is *Save as...* (fork what is on screen into a new name), *Switch
+to*, and *Manage*.
+
+One is active at a time, and that is not a simplification. The most
+load-bearing thing a workspace holds is which probe and which target, and a
+probe is connected to one target: two workspaces open at once would either
+share the probe, in which case they are not independent, or each want it for
+a different target, which is a contradiction rather than a feature.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+from pathlib import Path
+
+from pyflashgui.core import paths
+
+#: The one every installation has. Created silently, never deleted, and never
+#: named in the window title -- somebody who only ever has this one should not
+#: be able to tell that workspaces were built.
+DEFAULT = "default"
+
+#: Under the user folder: the workspaces themselves, and the note saying which
+#: of them is in use. The pointer is the only thing here that is not inside a
+#: workspace, because it is the one question asked before there is one.
+ROOT = "workspaces"
+POINTER = "workspaces.json"
+
+MAX_NAME = 64
+#: A workspace name is a folder name, so it has to survive being one. Letters,
+#: digits, space, dot, dash and underscore, starting with a letter or a digit.
+_ALLOWED = re.compile(r"^[A-Za-z0-9][A-Za-z0-9 ._-]*$")
+
+#: The workspace ``--workspace`` named, for this run only. Kept out of the
+#: pointer so that a shortcut made for one product does not change what
+#: pyflashgui opens the next time it is started without one.
+_this_run = ""
+#: Windows refuses these as filenames whatever the extension, and has since
+#: DOS. A workspace called "con" would be created, apparently, and then be
+#: unopenable.
+_RESERVED = frozenset(
+    {"con", "prn", "aux", "nul"}
+    | {f"com{i}" for i in range(1, 10)}
+    | {f"lpt{i}" for i in range(1, 10)}
+)
+
+
+# --- where things are -------------------------------------------------------------------
+def root() -> Path:
+    return paths.user_dir() / ROOT
+
+
+def dir_for(name: str) -> Path:
+    return root() / name
+
+
+def _pointer() -> Path:
+    return paths.user_dir() / POINTER
+
+
+def _ensure() -> None:
+    """Make sure there is somewhere to work."""
+    paths.made(dir_for(DEFAULT))
+
+
+def names() -> list[str]:
+    """Every workspace, ``default`` first and the rest by name."""
+    _ensure()
+    found = sorted(p.name for p in root().iterdir() if p.is_dir())
+    return [DEFAULT, *(n for n in found if n != DEFAULT)]
+
+
+def exists(name: str) -> bool:
+    return bool(name) and dir_for(name).is_dir()
+
+
+def active() -> str:
+    """Which workspace is in use. ``default`` when nothing says otherwise."""
+    _ensure()
+    if _this_run and exists(_this_run):
+        return _this_run
+    try:
+        chosen = json.loads(_pointer().read_text(encoding="utf-8")).get("active")
+    except (OSError, ValueError, AttributeError):
+        return DEFAULT
+    # A workspace deleted by hand, or a pointer typed wrong, is not a reason
+    # to start with nothing: fall back to the one that is always there.
+    return chosen if isinstance(chosen, str) and exists(chosen) else DEFAULT
+
+
+def use(name: str) -> None:
+    """Work in this workspace this time, leaving the one opened next time alone."""
+    global _this_run
+    _this_run = name
+
+
+def set_active(name: str) -> None:
+    use("")  # a workspace chosen in the window is chosen for good
+    _pointer().write_text(json.dumps({"active": name}, indent=2), encoding="utf-8")
+
+
+def active_dir() -> Path:
+    _ensure()
+    return _made(dir_for(active()))
+
+
+def settings_path() -> Path:
+    return active_dir() / "settings.json"
+
+
+def layout_path() -> Path:
+    return active_dir() / "layout.json"
+
+
+def _made(path: Path) -> Path:
+    return paths.made(path)
+
+
+# --- naming one -------------------------------------------------------------------------
+def clean(name: str) -> str:
+    """The name as it will actually be used.
+
+    Only the space around it, which nobody typed on purpose. Everything else
+    is left alone and refused by name below rather than quietly repaired:
+    turning "board 1/2" into "board 12" would leave somebody looking for a
+    workspace that is not called what they called it.
+    """
+    return name.strip()
+
+
+def why_not(name: str) -> str:
+    """Why this name cannot be used, or "" if it can."""
+    name = clean(name)
+    if reason := _not_a_folder_name(name):
+        return reason
+    if exists(name):
+        return f"There is already a workspace called {name}."
+    return ""
+
+
+def _not_a_folder_name(name: str) -> str:
+    """Why this could never be a workspace, taken or not. "" if it could."""
+    if not name:
+        return "A workspace needs a name."
+    if len(name) > MAX_NAME:
+        return f"Names are at most {MAX_NAME} characters."
+    if not _ALLOWED.match(name) or name.endswith((" ", ".")):
+        return (
+            "A workspace name is also a folder name: letters, digits, spaces, "
+            "dots, dashes and underscores, starting with a letter or a digit."
+        )
+    if name.lower() in _RESERVED:
+        return f"Windows will not accept a folder called {name}."
+    return ""
+
+
+def next_free(base: str = "workspace") -> str:
+    """A name nobody has used, as close to ``base`` as it can be.
+
+    Offered, never imposed: it is what a name dialog opens on, so the easy
+    answer is one that will be accepted. A ``base`` that could never be a
+    folder name -- a downloaded file called "board (1)", say -- is not tidied
+    into something that looks like it; the suggestion falls back to plain
+    "workspace" and the person can type what they meant.
+    """
+    base = clean(base)
+    if _not_a_folder_name(base):
+        base = "workspace"
+    if not exists(base):
+        return base
+    number = 2
+    while True:
+        suffix = f" {number}"
+        # Shortened to fit rather than refused for length, which would never end.
+        candidate = base[: MAX_NAME - len(suffix)].rstrip(" .") + suffix
+        if why_not(candidate) == "":
+            return candidate
+        number += 1
+
+
+# --- making, renaming, removing -----------------------------------------------------------
+def create(name: str, copy_from: str | None = None) -> Path:
+    """A new workspace, optionally forked from an existing one.
+
+    Save as... forks, because what somebody means by it is "keep what I have
+    and start calling it something else". An empty new one would throw away
+    the arrangement they were looking at when they asked.
+    """
+    if (reason := why_not(name)) != "":
+        raise ValueError(reason)
+    name = clean(name)
+    target = dir_for(name)
+    if copy_from and exists(copy_from):
+        shutil.copytree(dir_for(copy_from), target)
+    else:
+        target.mkdir(parents=True)
+    return target
+
+
+def rename(old: str, new: str) -> None:
+    if old == DEFAULT:
+        raise ValueError(f"{DEFAULT} cannot be renamed: it is the one that is always there.")
+    if not exists(old):
+        raise ValueError(f"There is no workspace called {old}.")
+    if (reason := why_not(new)) != "":
+        raise ValueError(reason)
+    # Asked before the folder moves. Afterwards the pointer names something
+    # that is no longer there, so active() has already fallen back to default
+    # and the rename would quietly send somebody somewhere else.
+    was_active = active() == old
+    new = clean(new)
+    dir_for(old).rename(dir_for(new))
+    if was_active and _this_run == old:
+        use(new)
+    elif was_active:
+        set_active(new)
+
+
+def delete(name: str) -> None:
+    """Remove a workspace and everything in it.
+
+    Not the active one: pulling the settings and layout out from under
+    a running window is a worse answer than asking somebody to switch away
+    first, which is one click and leaves them somewhere they chose.
+    """
+    if name == DEFAULT:
+        raise ValueError(f"{DEFAULT} cannot be deleted: it is the one that is always there.")
+    if name == active():
+        raise ValueError(f"{name} is the workspace in use. Switch to another one first.")
+    if not exists(name):
+        raise ValueError(f"There is no workspace called {name}.")
+    shutil.rmtree(dir_for(name))

pyflashgui/help/__init__.py

@@ -0,0 +1,129 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""The manual, shipped with the application: a page per topic.
+
+Inside the package rather than beside the README so that it survives a
+``pip install`` and lands in the frozen build. A Help menu that needs the
+internet is worth nothing on a bench or in a workshop, which is where
+somebody is most likely to want it.
+
+Markdown, because it is the same text the repository serves on the web and Qt
+renders it directly -- ``QTextBrowser.setMarkdown`` with the GitHub dialect,
+so the tables come out as tables. No web engine: the GPL-only Qt modules are
+deliberately not installed, and a manual is not worth a web engine.
+
+**A page per pane, rather than one long file.**  Nobody reads a manual; people
+look one thing up in it, and a single document answers that by making them
+scroll past every topic they did not ask about. The pages are joined by
+ordinary relative Markdown links, so the same files read as pages on the
+repository's web view -- there is no navigation of ours to keep working in two
+places.
+
+The files are flat in this folder rather than in a ``pages/`` subdirectory,
+because the package data is declared as one glob and a subdirectory is exactly
+the kind of thing that ships in a wheel one release and not the next. The
+pictures the pages show sit beside them for the same reason, and the README
+uses the same files, so there is one copy of each.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+
+#: The front page, and the only name anything outside this module needs.
+MANUAL = "manual.md"
+
+#: Every page, the front one first. Listed rather than discovered so that a
+#: build that lost one fails with a name in it: ``--selftest`` checks this list
+#: against what actually shipped, and a manual quietly missing a page
+#: would otherwise be found by a user.
+PAGES = (
+    MANUAL,
+    "probe.md",
+    "files.md",
+    "memory-map.md",
+    "memory.md",
+    "about.md",
+    "changelog.md",
+)
+
+
+def page_text(name: str) -> str:
+    """One page as Markdown, or "" if this build did not ship it.
+
+    Empty rather than raising: a missing page should cost the reader that page,
+    not the application. ``pyflashgui --selftest`` fails on it instead, so a
+    build that dropped one is caught where it can still be fixed.
+
+    Only the pages named above are served. The name arrives from a link inside
+    a document, and a document is a thing that can be edited: reading whatever
+    path it asked for would turn a manual page into a way to open files.
+    """
+    if name not in PAGES:
+        return ""
+    try:
+        return resources.files(__name__).joinpath(name).read_text(encoding="utf-8")
+    except (OSError, ModuleNotFoundError):
+        return ""
+
+
+#: What a picture in the manual may be.
+IMAGE_SUFFIXES = (".png", ".jpg", ".jpeg", ".gif")
+
+
+def image_bytes(name: str) -> bytes:
+    """A picture a page shows, or b"" if it is not one this build shipped.
+
+    The same rule as ``page_text``, for the same reason: the name comes from a
+    document. Only a plain file name with an image suffix is read, from this
+    package and nowhere else -- no folders, and nothing that is not a picture.
+    """
+    if (
+        not name
+        or "/" in name
+        or "\\" in name
+        or name.startswith(".")
+        or not name.lower().endswith(IMAGE_SUFFIXES)
+    ):
+        return b""
+    try:
+        return resources.files(__name__).joinpath(name).read_bytes()
+    except (OSError, ModuleNotFoundError):
+        return b""
+
+
+def images_in(text: str) -> list[str]:
+    """Every picture a page shows, by the name it asks for."""
+    import re
+
+    return re.findall(r"!\[[^\]]*\]\(([^)\s]+)", text)
+
+
+def missing_images() -> list[str]:
+    """The pictures some page shows that this build cannot find."""
+    return sorted(
+        {name for page in PAGES for name in images_in(page_text(page)) if not image_bytes(name)}
+    )
+
+
+def manual_text() -> str:
+    """The front page: the contents, and the way in to every other page."""
+    return page_text(MANUAL)
+
+
+def title_of(name: str) -> str:
+    """What a page calls itself, taken from its first heading."""
+    for line in page_text(name).splitlines():
+        if line.startswith("# "):
+            return line[2:].strip()
+    return name
+
+
+def all_text() -> str:
+    """Every page, joined. For asking whether the manual covers something."""
+    return "\n\n".join(page_text(name) for name in PAGES)
+
+
+def missing_pages() -> list[str]:
+    """The pages that ought to have shipped and did not."""
+    return [name for name in PAGES if not page_text(name).strip()]

pyflashgui/help/about.md

@@ -0,0 +1,21 @@
+[← Contents](manual.md)
+
+# About, licences and updates
+
+**Help > Documentation** opens this manual. It ships inside pyflashgui; *Back* and *Contents* get you around it.
+
+**Help > Diagnostics...** writes a report of the versions of pyflashgui, Python and every package it runs on, and any panes out on their own, to the Event Log and copies it to the clipboard -- ready to paste into a bug report.
+
+The report names the version, and -- when pyflashgui is being run from a source checkout rather than an installed build -- the branch or tag and the commit it is on, read from `.git` without running git. Between two releases every build calls itself the same version, so that line is what tells one pull from another. It does not say whether any file has been edited since: that needs git itself, and the launcher runs without a console for it to use.
+
+**Help > Check for updates...** asks the question that fits how pyflashgui was installed. The Windows installer's build asks GitHub whether there is a newer release, and offers to open the releases page. A pip installation asks PyPI for its newest version, and says the pip command that updates it. Run from a source folder, it asks about commits instead, since a release is behind everything pulled since: how many newer commits GitHub has on the branch this folder is on, and it offers to open the list of them. A branch GitHub does not have is compared with master.
+
+**Help > Licences...** shows pyflashgui's own Apache-2.0 licence, the NOTICE attributions and the full third-party licence text, all shipped with the application.
+
+**Help > About pyflashgui** shows the version alongside Python, every package pyflashgui runs on and the platform, in a form you can copy. It also says where it is running from: the Python it started with, that Python's environment, the folder the pyflashgui package was loaded from, and how it got there -- pip, an editable install of a source folder, or the Windows installer. On a computer with more than one Python that answers which one it is.
+
+## If pyflashgui will not start
+
+Started from the source folder, `pyflashgui.cmd` and `pyflashgui.sh` install anything missing before they start pyflashgui, and a library that is still missing is reported in a window rather than as nothing happening. On Linux, a library Qt needs to draw the window is named, with the package it comes in, before Qt is started: Qt itself says only that it could not load the "xcb" plugin. `python -m pyflashgui --selftest` imports everything a build is most likely to be missing, checks that pyOCD can find its probe drivers and targets, and exits with 0 if it is all there, which is how the build checks itself.
+
+**If pyflashgui is slow to start**, the diagnostics report says where the seconds went: starting is measured on every run, step by step and package by package, so the breakdown is already there when somebody thinks to ask. A start that takes longer than usual says so in the Event Log and points to *Help > Diagnostics*. The first start after an update is the usual one: Python compiles every changed file again, and that start says how many it compiled. To have the whole report in the Event Log after every start, and in `startup-timing.txt` in pyflashgui's own folder, start pyflashgui with `--timing` -- `pyflashgui.cmd --timing`, or `pyflashgui.sh --timing` -- or set `PYFLASHGUI_TIMING=1`.