[doc] Document how to avoid symbol clashes with embedder

[dcharkes]

Closes: #2724

cc @simolus3

[github-actions]

PR Health

License Headers ✔️

// Copyright (c) 2025, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

Files
no missing headers

All source files should start with a license header.

Unrelated files missing license headers

Files
pkgs/objective_c/lib/src/ns_input_stream.dart

This check can be disabled by tagging the PR with skip-license-check.

[coveralls]

coverage: 82.383%. remained the same
when pulling 62ff7f8 on doc-code-assets-linking
into 62e7c9b on main.

[simolus3]

Thanks for documenting this 👍

[simolus3]

Just my two cents: This isn't trivial to get right. Because if I do say

int my_package_sqlite3_open_v2(
  const char *filename,
  sqlite3 **ppDb,
  int flags,
  const char *zVfs
) {
  return sqlite3_open_v2(filename, ppDb, flags, zVfs);
}

and use the default options from native_toolchain_c to link that and sqlite3.c into a shared library, my understanding is that sqlite3_open_v2 from the previously loaded library takes precedence over the sqlite3_open_v2 defined in the my wrapper library.

I think if I compile sqlite3.c with -fvisibility=hidden this could work, but then it's essentially the same thing as approach 2 with extra steps.

[dcharkes]

So, this only works with the option to use the system library for space savings,
not with a custom library.