Moving all FFI examples into tutorials (#4429)

I've updated them to be runnable outside the workspace. This is tested
as the `docs` folder is excluded from the workspace.

I moved `patch.toml` into `docs/tutorials/.cargo/config.toml` so that it
automatically applies to every cargo invocation in tutorials. The
crates-io test deletes the config, it already mutates the repo by
deleting the `Cargo.lock`, and it's on borrowed time anyway.

I've also found a better way of building static and dynamic libraries
using `cargo rustc`. This way clients don't need to create wrapper
crates anymore. They still have to create a `Cargo.toml` to pull in
`icu_capi`, but they don't need a whole crate.

I've removed all usages of `icu_capi_{staticlib,cdylib}` both internally
and from tutorials. I suggest we phase out these crates soon.

.github/workflows/artifacts-build.yml

@@ -184,7 +184,7 @@ jobs:
     - name: Build docs
       run: |
         cd ffi/npm
-        make lib/index.js
+        make lib/index.mjs
         npm install typedoc
         node_modules/typedoc/bin/typedoc lib/index.d.ts --out docs --readme ../../docs/tutorials/js.md --basePath lib
         cd ../..
@@ -280,19 +280,19 @@ jobs:
     - name: Init packages
       run: |
         npm -C ffi/npm ci
-        npm -C ffi/npm/examples/wasm-demo ci
+        npm -C docs/tutorials/npm ci
 
     - name: Run Webpack
-      run: npm -C ffi/npm/examples/wasm-demo run build
+      run: npm -C docs/tutorials/npm run build
 
     - name: Put index.html in dist for temp URL
       run: |
-        cp ffi/npm/examples/wasm-demo/index.html ffi/npm/examples/wasm-demo/dist/index.html
-        printf "const gcs=document.createElement('script');gcs.setAttribute('src','./bundle.js');document.body.appendChild(gcs);" > ffi/npm/examples/wasm-demo/dist/index.js
+        cp docs/tutorials/npm/index.html docs/tutorials/npm/dist/index.html
+        printf "const gcs=document.createElement('script');gcs.setAttribute('src','./bundle.js');document.body.appendChild(gcs);" > docs/tutorials/npm/dist/index.js
 
     - name: Upload wasm-demo bundle to Google Cloud Storage
       run: |
-        gsutil -m cp -r ffi/npm/examples/wasm-demo/dist/* gs://${{ env.GCP_MAIN_BUCKET_ID }}/gha/wasm-demo
+        gsutil -m cp -r docs/tutorials/npm/dist/* gs://${{ env.GCP_MAIN_BUCKET_ID }}/gha/wasm-demo
 
     - name: "⭐⭐⭐ Links to Uploaded Artifacts ⭐⭐⭐"
       run: |

Cargo.toml

@@ -5,7 +5,7 @@
 [workspace]
 resolver = "2"
 members = [
-    # KEEP IN SYNC WITH workspace.dependencies and docs/tutorials/testing/patch.toml
+    # KEEP IN SYNC WITH workspace.dependencies and docs/tutorials/.cargo/config.toml
 
     # Components
     "components/calendar",
@@ -99,6 +99,7 @@ members = [
     "tools/diplomat-gen",
     "tools/ffi_coverage",
     "tools/testdata-scripts",
+    "tools/md-tests",
 ]
 # Note: Workspaces in subdirectories, such as docs/tutorials/crates, are
 # implicitly excluded from the main workspace.
@@ -110,8 +111,7 @@ exclude = [
     # in the repo it doesn't build without running `cargo make testdata-legacy`
     # first.
     "provider/testdata",
-    # Tutorials are tested in their own cargo workspace against released and
-    # local crates
+    # Tutorials are tested outside the workspace to simulate external users
     "docs",
     # Not a functioning crate
     "provider/baked/_template_",
@@ -138,7 +138,7 @@ include = [
 ]
 
 [workspace.dependencies]
-# KEEP IN SYNC WITH workspace.members and docs/tutorials/testing/patch.toml
+# KEEP IN SYNC WITH workspace.members and docs/tutorials/.cargo/config.toml
 
 # Components
 icu = { version = "~1.4.0", path = "components/icu", default-features = false }

Makefile.toml

@@ -249,7 +249,7 @@ dependencies = [
     # Get a coffee
     "ci-job-test",
     "ci-job-test-docs",
-    "ci-job-check-tutorials-cratesio",
+    "ci-job-test-tutorials-cratesio",
     "ci-job-diplomat",
     "ci-job-testdata",
     "ci-job-msrv-features",

docs/tutorials/testing/patch.toml → docs/tutorials/.cargo/config.toml

@@ -2,6 +2,10 @@
 # called LICENSE at the top level of the ICU4X source tree
 # (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
 
+# All code in tutorials is built outside the workspace, as a client would.
+# In order to test with repo code, this config.toml is used automatically
+# by cargo for any invocation inside docs/tutorials/.
+
 [patch.crates-io]
 # KEEP IN SYNC WITH TOP-LEVEL Cargo.toml
 

ffi/capi/tests/tinyc/fixeddecimal/crate/Cargo.toml → docs/tutorials/c-tiny/fixeddecimal/crate/Cargo.toml

@@ -6,16 +6,13 @@
 name = "crate"
 publish = false
 version = "0.0.0"
-edition = "2021"
 
 [lib]
 crate-type = ["staticlib"]
 
 [dependencies]
-icu_capi = { path = "../../../..", default-features = false, features = ["compiled_data", "icu_decimal"] }
+icu_capi = { version = "1.4", default-features = false, features = ["compiled_data", "icu_decimal"] }
 dlmalloc = { version = "0.2", features = ["global"] }
 
 [features]
 std = []
-
-[workspace]