[MacPorts] WimplicitFunctionDeclaration modified

[MacPorts Wiki]

Page "WimplicitFunctionDeclaration" was changed by JDLH
Diff URL: <https://trac.macports.org/wiki/WimplicitFunctionDeclaration?action=diff&version=6>
Revision 6
Comment: New sections, "Add names to implicit declaration whitelist" and "Add names to whitelist via Portfile"
Changes:
-------8<------8<------8<------8<------8<------8<------8<------8<--------
Index: WimplicitFunctionDeclaration
=========================================================================
--- WimplicitFunctionDeclaration (version: 5)
+++ WimplicitFunctionDeclaration (version: 6)
@@ -213,6 +213,35 @@
 
 This code, and its counterpart in `configure`, are a good place to examine closely for incorrect behaviour. Does the configuration come to the wrong conclusion about the capabilities of the compiler? If so, that is exactly the "features were… accidentally disabled" risk which the original warning was bringing to your attention.
 
+== Add names to implicit declaration whitelist ==
+
+In cases where you have confirmed that a function name is not declared by the include file which should declare it, for a certain macOS SDK, then add that name to whitelists in the MacPorts codebase. This means that, when the compiler generates a `-Wimplicit-function-declaration` warning for that name, MacPorts will not elevate that warning to the `main.log`. Thus it will not cause concern to MacPorts users who use ports which test for that fucntion name. 
+
+The whitelists are in the MacPorts codebase at `[https://github.com/macports/macports-ports/tree/master/_resources/port1.0/checks/implicit_function_declaration _resources/port1.0/checks/implicit_function_declaration]`. There is a separate whitelist for each version of the macOS SDK: macOS 10.5, macOS 10.14, macOS 11.0 (stored as macOS 11), etc. Each whitelist is a text file containing a list of C language function names, one per line, in lexical order.
+
+To add a name to the whitelist, first convince yourself that the name is in fact no declared by the include file which should declare it, by creating a brief test program which uses that function. Compile that file with a compiler invocation similar to what MacPorts uses, including `-Werror`. The compiler will implicitly add `-Wimplicit-function-declaration` if it is recent enough to be able to compile ARM code. The compilation should fail with an error message like, 
+
+{{{
+warning: implicitly declaring library function '…' with type '…'
+      [-Wimplicit-function-declaration]
+}}}
+
+You may be able to test using multiple different versions of the macOS SDK. That is good. It is desireable to add a function name to all the whitelists to which it applies.
+
+Then create a Pull Request modifying the whitelist file(s) appropriate for the version(s) of the macOS SDK which you have tested. The change will be simple: to add a line to the file, inserting a new line with the function name, in the correct lexical order. This change will take effect when the user downloads a new version of the MacPorts base code. It applies to all ports, when configured on the version of macOS which corresponds to the whitelist file.
+
+
+== Add names to whitelist via Portfile ==
+
+Another approach is to add the function name via the Portfile, via a line like:
+{{{
+configure.checks.implicit_function_declaration.whitelist-append strchr
+}}}
+
+This adds the function name (in this example, `strchr` to the whitelist for the current Portfile, regardless of macOS SDK version.
+
+**TODO**: explain when it is better to change the whitelists, and when it is better to add a `configure.checks.implicit_function_declaration.whitelist-append` to the Portfile.
+
 == Respond by filing upstream bug reports ==
 
 If you can, please report these indications to the upstream developers. It is far better to have the upstream developers change their code so that it works with Xcode 12 and on ARM processors, along with all the other compilers and processors where it needs to work. 
@@ -247,3 +276,8 @@
   * [https://www.gnu.org/software/autoconf/ GNU Autoconf] project: https://www.gnu.org/software/autoconf/
   * [https://www.gnu.org/software/m4/m4.html GNU M4] project: https://www.gnu.org/software/m4/m4.html
 
+=== MacPorts code ===
+
+Want to learn now a feature really works? As the wise teachers say, "Read the source, Luke."  Here are links to MacPorts source code which relates to the -Wimplicit-function-declaration warning.
+
+  * [https://github.com/macports/macports-base/blob/13b4fc42766bfb15fe6aa7b8e5aa1364dc632158/src/port1.0/portconfigure.tcl#L1785-L1835 portconfigure.tcl#L1785-L1835], where the `port` core code reads the whitelist and issues the -Wimplicit-function-declaration warning.
-------8<------8<------8<------8<------8<------8<------8<------8<--------

--
Page URL: <https://trac.macports.org/wiki/WimplicitFunctionDeclaration>
MacPorts <https://www.macports.org/>
Ports system for macOS

This is an automated message. Someone added your email address to be
notified of changes on 'WimplicitFunctionDeclaration' page.
If it was not you, please report to admin at macports.org.