| 216 | == Add names to implicit declaration whitelist == |
| 217 | |
| 218 | 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. |
| 219 | |
| 220 | 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. |
| 221 | |
| 222 | 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, |
| 223 | |
| 224 | {{{ |
| 225 | warning: implicitly declaring library function '…' with type '…' |
| 226 | [-Wimplicit-function-declaration] |
| 227 | }}} |
| 228 | |
| 229 | 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. |
| 230 | |
| 231 | 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. |
| 232 | |
| 233 | |
| 234 | == Add names to whitelist via Portfile == |
| 235 | |
| 236 | Another approach is to add the function name via the Portfile, via a line like: |
| 237 | {{{ |
| 238 | configure.checks.implicit_function_declaration.whitelist-append strchr |
| 239 | }}} |
| 240 | |
| 241 | This adds the function name (in this example, `strchr` to the whitelist for the current Portfile, regardless of macOS SDK version. |
| 242 | |
| 243 | **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. |
| 244 | |