Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Local out of tree usermods fail to find dependencies

Aperta
  • Qualcosa non va?
#5,802 1 commento 0 reazioni 1 assegnatario Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@willmmiles ci sta già lavorando.

Dal 16/8/2026.

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

AI bug

Issue description

Problem

An out-of-tree usermod wired in via a plain local path, e.g.

custom_usermods =
  ${env:esp32dev.custom_usermods}
  symlink://../my-usermod

fails to compile with:

fatal error: wled.h: No such file or directory

even though the symlink resolves correctly and the usermod's own sources are
found and compiled (they just don't see WLED's own include path).

This only happens for local symlink:///file:// entries. The same line
written as github.com/user/my-usermod or https://github.com/user/repo.git
works fine, and the explicit named form

custom_usermods =
  my-usermod = symlink://../my-usermod

is also a working workaround.

Root cause

pio-scripts/load_usermods.py decides whether a resolved library dependency
is a WLED module (and therefore gets WLED's include path added to it) in
is_wled_module():

def is_wled_module(dep: LibBuilderBase) -> bool:
  return (
    usermod_dir in Path(dep.src_dir).parents
    or str(dep.name).startswith("wled-")
    or dep.name in _custom_usermod_names
  )

For an out-of-tree usermod that is neither inside usermods/ nor named
wled-*, this relies entirely on dep.name being present in
_custom_usermod_names, which is populated ahead of time by
_predict_dep_name() while parsing the raw custom_usermods option.

_predict_dep_name() only extracts a name from the URL path when
parsed.netloc is github.com, gitlab.com or bitbucket.com:

if _URL_SCHEME_RE.match(entry):
  parsed = urlparse(entry)
  if parsed.netloc in ('github.com', 'gitlab.com', 'bitbucket.com'):
    parts = [p for p in parsed.path.split('/') if p]
    if len(parts) >= 2:
      name = parts[1]
    else:
      name = Path(parsed.path.rstrip('/')).name.strip()
    if name.endswith('.git'):
      name = name[:-4]
    return name or None
# falls through to SSH / '@' / plain "owner/Name" checks, none of which
# match a "symlink://..." string, so the function returns None

For symlink://../my-usermod (or any other non-git-host URL, including
symlink:///absolute/path and file://...), parsed.netloc is not one of
the three known hosts, so the if body - and therefore the return - is
never reached. The function falls through the remaining SSH/@/plain-name
checks (none of which match a URL string) and returns None at the very
end. A WARNING: Cannot determine library name for custom_usermods entry
is printed, but the build continues without the name being registered - and
because the module was silently not recognised as a WLED module, WLED's
include path is silently missing from that compilation unit, which only
surfaces later as a wled.h: No such file or directory in each of that
usermod's source files.

Worth noting: urlparse() puts the first path segment after // into
.netloc, not .path, whenever there is one (e.g.
urlparse("symlink://../foo") → netloc='..', path='/foo'); only a URL
with an empty authority section (symlink:///abs/path, three slashes)
gets the whole thing in .path. Any fix needs to account for both forms.

Possible Fix

Give the else branch (any URL whose host isn't a known git forge -
i.e. every local symlink:///file:// path, plus self-hosted git servers)
the same "last path segment is the library name" fallback the git-host
branch already uses, instead of falling through to None. netloc and
path are stitched back together first so both symlink://../foo (netloc
non-empty) and symlink:///abs/path/foo (netloc empty) resolve to the same
foo:

  # URL scheme: extract name from path
  if _URL_SCHEME_RE.match(entry):
    parsed = urlparse(entry)
    if parsed.netloc in ('github.com', 'gitlab.com', 'bitbucket.com'):
      parts = [p for p in parsed.path.split('/') if p]
      name = parts[1] if len(parts) >= 2 else Path(parsed.path.rstrip('/')).name.strip()
    else:
      # Local paths (symlink://, file://) and any other host: fall back to
      # the last path segment, same as PlatformIO does for a local/symlinked
      # library without a manifest override. urlparse puts the first path
      # component into .netloc when the URL's authority section isn't
      # empty (e.g. "symlink://../foo" -> netloc="..", path="/foo"), so
      # stitch them back together before taking the last segment - this
      # also covers absolute paths ("symlink:///abs/path/foo") where
      # netloc is already empty.
      full_path = parsed.netloc + parsed.path if parsed.netloc not in ('', 'localhost') else parsed.path
      name = Path(full_path.rstrip('/')).name.strip()
    if name.endswith('.git'):
      name = name[:-4]
    return name or None

Disclaimer: Issue found and proposed fix made by AI.

Lingua principale
C++
Stelle
18.8k
Fork
4.4k
Merge medio
4g 6h
PR unite (30g)
12

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di wled/WLED

Tutte le issue di wled/WLED

Issue simili

Altre issue su C++

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.