Docs for building with an ICU source directory don't work

[catamorphism]

Version

N/A

Platform

Linux tjc-ThinkPad 6.8.0-86-generic #87-Ubuntu SMP PREEMPT_DYNAMIC Mon Sep 22 18:03:36 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux

Subsystem

No response

What steps will reproduce the bug?

1. Download a source distribution of ICU into $HOME/icu
2. Clone the node repo into node.
3. cd node && ./configure --with-intl=full-icu --with-icu-source=$HOME/icu

This initially fails to find uvernum.h. After changing the command as follows:

./configure --with-intl=full-icu --with-icu-source=$HOME/icu/icu4c

it fails with:

Node.js configure: Found Python 3.12.3...
Deleting old ICU source: deps/icu
$HOME/icu/icu4c -> deps/icu
ERROR: ICU prebuilt data file deps/icu/source/data/in/icudt77l.dat does not exist.
       See the README.md.

If ICU is built with a separate build directory icu/build, then this file is found in icu/build/data/out/tmp/icudt79l.dat. When I copied this file into icu/source/data/in, and re-ran the configure command again, it worked.

The documentation should be updated to reflect these extra steps.

How often does it reproduce? Is there a required condition?

See above

What is the expected behavior? Why is that the expected behavior?

See above

What do you see instead?

See above

Additional information

No response

[azadgupta1]

I would like to work on this issue. The problem seems to be with the outdated
documentation for building Node with a custom ICU source directory.

I’ll update the docs to include:

• Using --with-icu-source=/icu/icu4c instead of the top directory
• Explaining where modern ICU versions generate the icudt*.dat file
• Mentioning that this file needs to be copied to source/data/in for
  Node’s configure script to detect it correctly

Let me know if this approach sounds good.

[Renegade334]

Which tarball are you extracting?

If you're definitely extracting the correct icu4c-...-sources archive, then this is an issue with configure.py. The package structure seems to be different to what you're describing, so I wonder if you're working with something different.

cc @nodejs/build

[richardlau]

@srl295 Do you know if the directory structure of the upstream ICU tarballs changed since the Node.js documentation was written?

[srl295]

Hi @catamorphism
@richardlau the above structure isn't using a tarball, it's using a download from the ICU repo. It would work if the ICU source .tgz were used

[catamorphism]

Which tarball are you extracting?

@Renegade334 I didn't use a tarball, but rather a git checkout of ICU. I see now that the instructions imply you should use an unpacked tarball, but my initial reading of it was that any source directory would work, so maybe there's a bit of clarification that could be done if the docs are meant to only work with a downloaded tarball?

[srl295]

Which tarball are you extracting?

@Renegade334 I didn't use a tarball, but rather a git checkout of ICU. I see now that the instructions imply you should use an unpacked tarball, but my initial reading of it was that any source directory would work, so maybe there's a bit of clarification that could be done if the docs are meant to only work with a downloaded tarball?

It needs a downloaded tarball because of how it integrates the data. You can make one from an ordinary icu build with make dist if desired. Would be great to improve the docs; they don't say this on a quick perusal.

[Renegade334]

Would be great to improve the docs; they don't say this on a quick perusal.

The ICU documentation URL and source tarball naming scheme have also changed, if anyone chooses to pick this one up.

[srl295]

I would like to work on this issue. The problem seems to be with the outdated
documentation for building Node with a custom ICU source directory.

I’ll update the docs to include:

• Using --with-icu-source=/icu/icu4c instead of the top directory
• Explaining where modern ICU versions generate the icudt*.dat file
• Mentioning that this file needs to be copied to source/data/in for
  Node’s configure script to detect it correctly

Let me know if this approach sounds good.

Not quite so. But there is a doc addition needed