git clone https://github.com/unicode-org/icu.git
pushd icu/icu4c/source
# Run this and choose the platform and toolchain you prefer
./runConfigureICU --help# if macOS
./runConfigureICU macOS/gcc
# else if Linux (gcc is just an example, there are 5 Linux options)
./runConfigureICU Linux/gcc
# endexport DESTDIR=$ICU_SANDBOX/icu_release
make -j8 releaseDist
popd
Create a minimal C++ file here (we are in the $ICU_SANDBOX folder) called hello_mf2.cpp (click to view and/or download). The contents are reproduced below.
g++ hello_mf2.cpp -I$DESTDIR/usr/local/include -std=c++17 -L$DESTDIR/usr/local/lib -licuuc-licudata-licui18n# if macOSDYLD_LIBRARY_PATH=$DESTDIR/usr/local/lib ./a.out
# else if LinuxLD_LIBRARY_PATH=$DESTDIR/usr/local/lib ./a.out
# end
This will output
Hello John, today is January 28, 2025!
C++ Windows with Visual Studio
From Visual Studio with minimal work
These instructions will use a release version of ICU4C (tested with 76.1) and a “Hello ICU world” project already created. They provide minimal effort that only requires downloading and opening in Visual Studio before using.
Note: the MessageFormat 2 implementation in a previously release version may be behind the spec in the first few releases of ICU after the MF2.0 spec was declared 1.0 in CLDR 46.1, which occurred between ICU 76 and ICU 77. The difference between latest MF2.0 and the spec version supported in ICU may be minimal.
Create a minimal C++ file here (we are in the $ICU_SANDBOX folder). Call it hello_mf2.cpp. The link to download and the contents are listed above (see the Linux section).
Build your application and run it
set DESTDIR=%ICU_SANDBOX%\icu_release
cl /std:c++17 /EHsc /I %DESTDIR%\include %DESTDIR%/lib64/*.lib hello_mf2.cpp
rem set PATH only once, not every time
set PATH=%DESTDIR%\bin64;%PATH%
.\hello_mf2.exe
This will output
Hello John, today is January 28, 2025!
From Visual Studio (UI)
Prepare a sandbox folder. Call it hello_icu_mf2.
Build ICU4C (you only need to do this once)
Clone the ICU repository from https://github.com/unicode-org/icu to the hello_icu_mf2 folder. We will end up with the folder hello_icu_mf2\icu.
Start Visual Studio.
Select “Open a project or solution”
Open the allinone.sln solution from the hello_icu_mf2\icu\icu4c\source\allinone folder.
Select the “Build” – “Configuration Manager” menu
Change the active solution to “Release” and “x64” (or another architecture, but you will have to be consistent everywhere after this)
Select the “Build” – “Build solution” menu
Select the “File” – “Close solution” menu
Create a minimal C++ project in the hello_icu_mf2 folder. Call it hello_mf2.
You are still in Visual Studio. Select “Create a new project”
Choose the project template “Console App” (tagged C++, Windows, Console)
Click the “Next” button
Set the “Project name” to “HelloMF2” and set the “Location” to the hello_icu_mf2 folder. \
Click “Create”
A project will be created in the hello_icu_mf2\HelloMF2 folder.
Create a macro pointing to the ICU folder with the files we built.
Select the “View” – “Property Manager” menu
In the new dialog select the root of the tree (“HelloMF2”, not the Debug / Release leafs)
Right click and select “Add New Project Property Sheet…”
Call it IcuPropertySheet.props and click “Add”
Open (double-click) IcuPropertySheet in any of the “leafs” of the tree on the left. For example in HelloMF2 / Release | 64 / IcuPropertySheet
Select “User Macros” under “Common Properties” (left tree)
Click the “Add Macro” button
Name it IcuDistro and set the “Value” to the ..\icu\icu4c folder. If the test project we created is not in hello_icu_mf2, next to icu, then you can use a full path to the ICU folder where you just did a built. You can also point it to one you downloaded (from the GitHub releases, see above).
Click the “OK” button
Configure the project
Select HelloMF2 in the left-side tree
Select the “Project” – “Properties” menu
For “Configuration” (top-left) select “All Configurations”
For “Platform” (top-right) select “All Platforms”
In the left side tree:
“C/C++” / “General” set “Additional Include Directories” to $(IcuDistro)\include;%(AdditionalIncludeDirectories)
“C/C++” / “Language” set “C++ Language Standard” to ISO C++17 Standard (/std:c++17)
“Linker” / “General” set “Additional Dependencies” to icudt.lib;icuin.lib;icuuc.lib;$(CoreLibraryDependencies);%(AdditionalDependencies)
“Linker” / “General” set “Additional Library Directories” to $(IcuDistro)/lib64;%(AdditionalLibraryDirectories)
“Debugging” set “Environment” to PATH=$(IcuDistro)/bin64;%PATH%
For “Platform” (top-right) select “Win32”
In the left side tree remove the 64 in two of the settings:
“Linker” / “General” set “Additional Library Directories” to $(IcuDistro)/lib;%(AdditionalLibraryDirectories)
“Debugging” set “Environment” to PATH=$(IcuDistro)/bin;%PATH%
Update the default source file to use some ICU functionality
Select the “View” – “Solution Explorer” menu
In the left-side tree “HelloMF2” / “Source Files” open HelloMF2.cpp
Download the hello_mf2.cpp file (see earlier in this page for download link) and save it as HelloMF2.cpp, thereby replacing it.
At this point you should be able to build and run the application, debug it, etc.
When run, it will output
Hello John, today is January 28, 2025!
Java
We will assume that if you are interested in testing a pre-release Java library you already have (or know how to install) a JDK, Apache Maven, git, know how to create a project in your favorite IDE, and so on.
What you need
JDK, any version between 8 and 23
Apache Maven
Instructions
Create a new Maven project
mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=hello_icu_mf2 -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.5 -DinteractiveMode=false
cd hello_icu_mf2
Modify the pom.xml file
The project created as above uses the Java 17 version. If you are using a lower version then change <maven.compiler.release> property to whatever Java version you are using.
# Example on how to set the Java version to 11
mvn versions:set-property -Dproperty=maven.compiler.release -DnewVersion=11