I'm trying to build the ESP-IDF documentation (v5.4.1) on Windows, following all the official steps including setting up the environment and installing Doxygen.
After running export.bat and then build-docs -l en in the docs directory, the build process fails with an OSError: cannot load library 'libxcb.dll': error 0x7e. It also mentions ctypes.util.find_library() couldn't locate it.
It seems to be related to cairosvg and xcffib trying to load this DLL.
Has anyone encountered this issue when building ESP-IDF docs? Any tips on how to resolve this libxcb.dll dependency on Windows?
Full traceback is in the comments if needed!
Thanks in advance for any help!
Code: Select all
C:\Espressif\frameworks\esp-idf-v5.4.1>export.bat
Activating ESP-IDF 5.4
Setting IDF_PATH to 'C:\Espressif\frameworks\esp-idf-v5.4.1'.
* Checking python version ... 3.13.3
* Checking python dependencies ... OK
* Deactivating the current ESP-IDF environment (if any) ... OK
* Establishing a new ESP-IDF environment ... OK
* Identifying shell ... cmd.exe
* Detecting outdated tools in system ... Found tools that are not used by active ESP-IDF version.
For removing old versions of idf-driver, idf-python-wheels use command 'python.exe C:\Espressif\frameworks\esp-idf-v5.4.1\tools\idf_tools.py uninstall'
To free up even more space, remove installation packages of those tools.
Use option python.exe C:\Espressif\frameworks\esp-idf-v5.4.1\tools\idf_tools.py uninstall --remove-archives.
Done! You can now compile ESP-IDF projects.
Go to the project directory and run:
idf.py build
C:\Espressif\frameworks\esp-idf-v5.4.1>cd docs
C:\Espressif\frameworks\esp-idf-v5.4.1\docs>build-docs -l en
Building without a target
Will use 1 parallel builds and 1 jobs per build
[{'build_dir': 'C:\\Espressif\\frameworks\\esp-idf-v5.4.1\\docs\\_build\\en\\generic', 'source_dir': 'C:\\Espressif\\frameworks\\esp-idf-v5.4.1\\docs\\en', 'language': 'en', 'target': 'generic', 'sphinx_parallel_jobs': 1, 'builders': ['html'], 'input_docs': [''], 'doxyfile_dir': '.', 'project_path': '../'}]
Building in build_dir: C:\Espressif\frameworks\esp-idf-v5.4.1\docs\_build\en\generic
Running 'C:\Espressif\python_env\idf5.4_py3.13_env\Scripts\python.exe -u -m sphinx.cmd.build -j 1 -b html -d C:\Espressif\frameworks\esp-idf-v5.4.1\docs\_build\en\generic\doctrees -w sphinx-warning-log.txt -v -D docs_to_build= -D config_dir=C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\esp_docs -D doxyfile_dir=C:\Espressif\frameworks\esp-idf-v5.4.1\docs -D project_path=C:\Espressif\frameworks\esp-idf-v5.4.1 C:\Espressif\frameworks\esp-idf-v5.4.1\docs\en C:\Espressif\frameworks\esp-idf-v5.4.1\docs\_build\en\generic\html'
en/generic: Running Sphinx v7.1.2
en/generic: Version: v5.4.1 Release: v5.4.1
en/generic: Git commit ID: 4c2820d377
en/generic: Git tag: v5.4.1
en/generic: Git commit ID: 4c2820d377
en/generic: Git tag: v5.4.1
en/generic: Adding copy buttons to code blocks...
en/generic:
en/generic: Traceback (most recent call last):
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinx\cmd\build.py", line 285, in build_main
en/generic: app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
en/generic: args.doctreedir, args.builder, args.confoverrides, args.status,
en/generic: args.warning, args.freshenv, args.warningiserror,
en/generic: args.tags, args.verbosity, args.jobs, args.keep_going,
en/generic: args.pdb)
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinx\application.py", line 229, in __init__
en/generic: self.setup_extension(extension)
en/generic: ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinx\application.py", line 402, in setup_extension
en/generic: self.registry.load_extension(self, extname)
en/generic: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinx\registry.py", line 441, in load_extension
en/generic: mod = import_module(extname)
en/generic: File "C:\Users\HP\AppData\Local\Programs\Python\Python313\Lib\importlib\__init__.py", line 88, in import_module
en/generic: return _bootstrap._gcd_import(name[level:], package, level)
en/generic: ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
en/generic: File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
en/generic: File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
en/generic: File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
en/generic: File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
en/generic: File "<frozen importlib._bootstrap_external>", line 1026, in exec_module
en/generic: File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinxcontrib\wavedrom.py", line 15, in <module>
en/generic: from .wavedrom_render_image import render_wavedrom_image
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinxcontrib\wavedrom_render_image.py", line 6, in <module>
en/generic: import cairosvg
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cairosvg\__init__.py", line 26, in <module>
en/generic: from . import surface # noqa isort:skip
en/generic: ^^^^^^^^^^^^^^^^^^^^^
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cairosvg\surface.py", line 9, in <module>
en/generic: import cairocffi as cairo
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cairocffi\__init__.py", line 18, in <module>
en/generic: from .ffi import ffi
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cairocffi\ffi.py", line 22, in <module>
en/generic: from xcffib.ffi import ffi as xcb_ffi
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\xcffib\__init__.py", line 35, in <module>
en/generic: lib = ffi.dlopen(soname)
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cffi\api.py", line 150, in dlopen
en/generic: lib, function_cache = _make_ffi_library(self, name, flags)
en/generic: ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cffi\api.py", line 834, in _make_ffi_library
en/generic: backendlib = _load_backend_lib(backend, libname, flags)
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cffi\api.py", line 829, in _load_backend_lib
en/generic: raise OSError(msg)
en/generic: OSError: cannot load library 'libxcb.dll': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libxcb.dll'
en/generic:
en/generic: Exception occurred:
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cffi\api.py", line 829, in _load_backend_lib
en/generic: raise OSError(msg)
en/generic: OSError: cannot load library 'libxcb.dll': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libxcb.dll'
en/generic: The full traceback has been saved in C:\Users\HP\AppData\Local\Temp\sphinx-err-4k7usn30.log, if you want to report the issue to the developers.
en/generic: Please also report this if it was a user error, so that a better error message can be provided next time.
en/generic: A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
C:\Espressif\frameworks\esp-idf-v5.4.1\docs\_build\en\generic\doxygen-warning-log.txt not generated
en/generic: Build failed due to new/different warnings (C:\Espressif\frameworks\esp-idf-v5.4.1\docs\_build\en\generic\sphinx-warning-log.txt):
en/generic: Traceback (most recent call last):
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinx\cmd\build.py", line 285, in build_main
en/generic: app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
en/generic: args.doctreedir, args.builder, args.confoverrides, args.status,
en/generic: args.warning, args.freshenv, args.warningiserror,
en/generic: args.tags, args.verbosity, args.jobs, args.keep_going,
en/generic: args.pdb)
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinx\application.py", line 229, in __init__
en/generic: self.setup_extension(extension)
en/generic: ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinx\application.py", line 402, in setup_extension
en/generic: self.registry.load_extension(self, extname)
en/generic: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinx\registry.py", line 441, in load_extension
en/generic: mod = import_module(extname)
en/generic: File "C:\Users\HP\AppData\Local\Programs\Python\Python313\Lib\importlib\__init__.py", line 88, in import_module
en/generic: return _bootstrap._gcd_import(name[level:], package, level)
en/generic: ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
en/generic: File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
en/generic: File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
en/generic: File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
en/generic: File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
en/generic: File "<frozen importlib._bootstrap_external>", line 1026, in exec_module
en/generic: File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinxcontrib\wavedrom.py", line 15, in <module>
en/generic: from .wavedrom_render_image import render_wavedrom_image
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinxcontrib\wavedrom_render_image.py", line 6, in <module>
en/generic: import cairosvg
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cairosvg\__init__.py", line 26, in <module>
en/generic: from . import surface # noqa isort:skip
en/generic: ^^^^^^^^^^^^^^^^^^^^^
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cairosvg\surface.py", line 9, in <module>
en/generic: import cairocffi as cairo
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cairocffi\__init__.py", line 18, in <module>
en/generic: from .ffi import ffi
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cairocffi\ffi.py", line 22, in <module>
en/generic: from xcffib.ffi import ffi as xcb_ffi
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\xcffib\__init__.py", line 35, in <module>
en/generic: lib = ffi.dlopen(soname)
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cffi\api.py", line 150, in dlopen
en/generic: lib, function_cache = _make_ffi_library(self, name, flags)
en/generic: ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cffi\api.py", line 834, in _make_ffi_library
en/generic: backendlib = _load_backend_lib(backend, libname, flags)
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cffi\api.py", line 829, in _load_backend_lib
en/generic: raise OSError(msg)
en/generic: OSError: cannot load library 'libxcb.dll': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libxcb.dll'
en/generic: Exception occurred:
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cffi\api.py", line 829, in _load_backend_lib
en/generic: raise OSError(msg)
en/generic: OSError: cannot load library 'libxcb.dll': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libxcb.dll'
en/generic: The full traceback has been saved in C:\Users\HP\AppData\Local\Temp\sphinx-err-4k7usn30.log, if you want to report the issue to the developers.
en/generic: Please also report this if it was a user error, so that a better error message can be provided next time.
en/generic: A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
en/generic: (Check files sphinx-known-warnings.txt and C:\Espressif\frameworks\esp-idf-v5.4.1\docs\_build\en\generic\sphinx-warning-log.txt for full details.)
[4]
The following language/target combinations failed to build:
language: en, target: generic, errcode: 4