Skip to content

docs: add rust_icu hello world example#366

Open
arnavnagzirkar wants to merge 3 commits into
google:mainfrom
arnavnagzirkar:fix-196
Open

docs: add rust_icu hello world example#366
arnavnagzirkar wants to merge 3 commits into
google:mainfrom
arnavnagzirkar:fix-196

Conversation

@arnavnagzirkar

Copy link
Copy Markdown

Adds a concise Hello World section to the README showing how to use rust_icu_umsg MessageFormat with rust_icu_common, rust_icu_uloc, and rust_icu_ustring dependencies.\n\nThis is a docs-only change.

@filmil

filmil commented Jun 3, 2026

Copy link
Copy Markdown
Member

How about an actual "examples subdir with the configurations you want to demo?

Address review: move the Hello, World! demo into a standalone, runnable
examples/hello_world crate (Cargo.toml + src/main.rs) instead of an inline
README snippet. The crate is excluded from the workspace so the CI feature
matrix is unaffected, and the top-level README now links to it.
@arnavnagzirkar

Copy link
Copy Markdown
Author

Good call — done. I moved the demo into a standalone, runnable examples/hello_world crate:

  • examples/hello_world/Cargo.toml — the exact dependency configuration to demo (rust_icu_common, rust_icu_uloc, rust_icu_umsg, rust_icu_ustring), with a comment showing the crates.io version alternative for downstream users.
  • examples/hello_world/src/main.rscargo run prints Hello, World!.
  • examples/hello_world/README.md — how to run it.

The crate is added to exclude in the root Cargo.toml so the CI feature matrix (cargo test --no-default-features --features ...) is unaffected, and the top-level README now links to the example instead of inlining the code.

@filmil

filmil commented Jun 3, 2026

Copy link
Copy Markdown
Member

Is this something that could be tied into presubmits? It would be much more useful if it's actually checked that it works.

Adds a test-examples CI job and a make docker-test-example target that build and run the examples/hello_world crate inside the existing dockerized test environment across ICU 74, 76 and 77. The example now exposes a greet() function with a unit test asserting the formatted output equals Hello, World!, so the presubmits verify the example compiles, runs and produces the expected output.
@arnavnagzirkar

Copy link
Copy Markdown
Author

Good idea. I have wired the example into the presubmits so it is actually verified on every push and pull request.

What I changed:

  • examples/hello_world/src/main.rs now puts the formatting logic in a greet() function with a #[test] that asserts the output equals Hello, World!, so the check verifies correctness and not just that the code compiles.
  • A new docker-test-example target in the Makefile builds and runs the example inside the same dockerized test environment the rest of the suite uses. It runs cargo test (the assertion) and then cargo run.
  • A new test-examples job in .github/workflows/test.yml runs that target across ICU 74, 76 and 77, matching the existing default feature matrix.

Because the example depends on the in tree crates with their default features, I kept it on the default feature configuration rather than the --no-default-features --features ... matrix, which targets the library crates. If the example ever stops compiling or stops printing Hello, World!, CI now fails.

You can reproduce the presubmit locally with:

make DOCKER_TEST_ENV=rust_icu_testenv-77 RUST_ICU_MAJOR_VERSION_NUMBER=77 docker-test-example

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants