Windows build instructions do not reference cairo version used by distribution

[thaDude]

On Windows, when comparing the canvas.node binary obtained from:

1. building locally following the instructions vs.
2. a regular npm install which uses available pre-builds.

I noticed that the local build happens against an older version of cairo which leads to conditional exclusion of the compilation of the cairo_pdf_surface_set_metadata not available in older versions of cairo, see Canvas.cc#L312.

Going through the releases of canvas this discrepancy has always existed going back to canvas 2.11.2 at least. This is problematic in the following case of a project using Node.js 22 and 2 different versions of canvas:

• canvas@3.2.0 : Windows x64 binary available on npm as pre-built native add-on.
• canvas@2.11.2 : Windows x64 binary not available on npm as as pre-built native add-on, local build with node-gyp required.

npm ls canvas
+-- canvas@3.2.0
+-- fabric@5.5.2
| +-- canvas@2.11.2
| `-- jsdom@19.0.0
|   `-- canvas@2.11.2 deduped
+-- jsdom@26.1.0
| `-- canvas@3.2.0 deduped
`-- svg2img@0.9.4
  +-- canvas@2.11.2
  `-- jsdom@16.7.0
    `-- canvas@2.11.2 deduped

Both canvas versions depend on libcairo-2.dll, however in my case, when the application starts the top level canvas@3.2.0's canvas.node binary seems to be linked to the wrong (older) libcairo-2.dll from my local canvas@2.11.2 build which misses cairo_pdf_surface_set_metadata, see WinDbg output below:

461c:3a88 @ 267532843 - LdrpNameToOrdinal - WARNING: Procedure "cairo_pdf_surface_set_metadata" could not be located in DLL at base 0x0000000068DC0000.
461c:3a88 @ 267532843 - LdrpReportError - ERROR: Locating export "cairo_pdf_surface_set_metadata" for DLL "\\?\C:\Users\<redacted>\Work\<redacted>\webapp\node_modules\canvas\build\Release\canvas.node" failed with status: 0xc0000139. (461c.3a88): Unknown exception - code c0000139 (first chance) 461c:3a88 @ 267532843 - LdrpGenericExceptionFilter - ERROR: Function LdrpSnapModule raised exception 0xc0000139 Exception record: .exr 0000009F1E7E5C30 Context record: .cxr 0000009F1E7E5740 461c:3a88 @ 267532843 - LdrpLoadDllInternal - RETURN: Status: 0xc0000139
461c:3a88 @ 267532843 - LdrpLoadDllInternal - RETURN: c0000139
461c:3a88 @ 267532843 - LdrLoadDll - RETURN: Status: 0xc0000139 461c:3a88 @ 267532843 - LdrLoadDll - RETURN: c0000139

Would it be possible to update the Windows build instructions to contain a link to a location which contains sufficiently reasonable cairo binaries - such as MYSYS2 which is used for the release pipeline? The expected default location for the libraries which currently defaults to --GTK_Root=C:\GTK during compilation could also be changed and ideally renamed. This way the conflict can be avoided when building locally?

If you know a better fix I am interested in hearing about it as well.

Regards,

David

[thaDude]

Would it be acceptable to do a 2.11.3 patch release which adds Node.js 22 to the build/release matrix?

I ended up doing what I described above, local build against dependencies installed via MYSYS2, upload of binaries (not the canvas package itself!) to some company internal location <canvas-binary-url>and then use npm install --canvas_binary_host_mirror=<canvas-binary-url>

[chearon]

Would it be possible to update the Windows build instructions to contain a link to a location which contains sufficiently reasonable cairo binaries - such as MYSYS2 which is used for the release pipeline?

We have this wiki article, seems like you may have found it from your second comment: https://github.com/Automattic/node-canvas/wiki/Installation:-Windows-(using-MSYS2)

If you know a better fix I am interested in hearing about it as well.

The 2x and 3x versions have been a huge pain in this regard, both for maintainers and users. The soon-to-be-released v4 produces a static build and uses up-to-date libraries on Windows even when you build locally. Follow #2602 for updates, and you can npm install canvas@next to try it now, though I think you still have to do something to get jsdom, fabric, and svg2img to use it.

I've turned down requests to keep 2.x maintained because it is a huge time sink to get 3.x binaries produced, let alone 2.x.

[thaDude]

Thank you for the explanations @chearon. I didn't see the wiki article since it isn't the one linked from the project's README.md - I just tried to reproduce what the Github actions do during the release process which lines up with what is explained in the article you mentioned.