Skip to content

Conversation

Empact
Copy link
Contributor

@Empact Empact commented Dec 11, 2018

This converts some dependency includes to use -isystem, so that we can
enable additional compiler checks and warnings independent of
the conformance of those dependencies.

The included new check is -Wdocumentation, which was previously proposed under #13914. See #14103 for examples of issues this has identified.

Here's a significant list of other clang checks we could consider given this. Some additional checks would require additional -isystem conversions, e.g. LevelDB is not converted here:
-Wreserved-id-macro
-Wthread-safety-attributes #15556
-Wthread-safety-negative
-Wfloat-equal
-Wfloat-conversion
-Wsign-conversion
-Wstring-conversion
-Wcast-qual
-Wcast-align
-Wshorten-64-to-32
-Wconversion
-Wfloat-conversion
-Wdouble-promotion
-Wshadow #15377
-Wshadow-field-in-constructor
-Wunused-exception-parameter
-Wunreachable-code-break
-Wdocumentation-unknown-command
-Wgnu-zero-variadic-macro-arguments
-Wgnu-anonymous-struct
-Wglobal-constructors
-Wexit-time-destructors
-Wnon-virtual-dtor
-Wweak-vtables
-Wcomma
-Wmissing-variable-declarations
-Wundefined-func-template
-Wzero-as-null-pointer-constant #15112
-Winconsistent-missing-destructor-override
-Wswitch-enum
-Wcovered-switch-default
-Wmissing-noreturn
-Wextra-semi
-Wc++17-extensions
-Wpadded
-Wold-style-cast
-Wmissing-prototypes

@DrahtBot
Copy link
Contributor

DrahtBot commented Dec 11, 2018

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Conflicts

Reviewers, this pull request conflicts with the following ones:

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

@practicalswift
Copy link
Contributor

Concept ACK

Thanks for working on this!

@laanwj
Copy link
Member

laanwj commented Dec 11, 2018

I think this can be useful for warnings.

Which compilers/versions is -isystem compatible with? does it need to be optional/tested?

@Empact
Copy link
Contributor Author

Empact commented Dec 11, 2018

For GCC, it has been available since 1994, the egcs days. gcc-mirror/gcc@0330c07

For Clang, has been in the codebase since at least 2009, coinciding with 2.7, though it wasn't mentioned in the release notes I checked. llvm-mirror/clang@33a33d8

MSVC has had a version of this since 2017, but AFAIK this should not affect those builds. https://blogs.msdn.microsoft.com/vcblog/2017/12/13/broken-warnings-theory/

@Empact
Copy link
Contributor Author

Empact commented Dec 12, 2018

Another option is -cxx-isystem, but I'm not sure there's a good reason to prefer it. Does build with all -isystem replaced with -cxx-isystem under current clang.

@fanquake
Copy link
Member

Concept ACK
Compiled on macOS, this doesn't have the problem with warnings that #13914 did.

@laanwj
Copy link
Member

laanwj commented Dec 13, 2018

For GCC, it has been available since 1994, the egcs days. gcc-mirror/gcc@0330c07
For Clang, has been in the codebase since at least 2009, coinciding with 2.7, though it wasn't mentioned in the release notes I checked. llvm-mirror/clang@33a33d8

TIL! Thanks for checking. That's far back enough, given that the minimum releases supported according to dependencies.md are gcc 4.8 and clang 3.3.

MSVC has had a version of this since 2017, but AFAIK this should not affect those builds. https://blogs.msdn.microsoft.com/vcblog/2017/12/13/broken-warnings-theory/

Right—MSVC is a different beast.

@laanwj
Copy link
Member

laanwj commented Dec 13, 2018

utACK—would be nice if @theuni could take a look at the build system changes.

@Empact Empact force-pushed the isystem branch 3 times, most recently from 8d363ce to 0ecc2db Compare December 14, 2018 11:39
@Empact
Copy link
Contributor Author

Empact commented Dec 14, 2018

In Makefile.leveldb.include, I split LEVELDB_CPPFLAGS_INT from LEVELDB_CPPFLAGS, and only gave the latter isystem treatment. The former is used for building leveldb as a lib, in which case the includes are not system includes.

I dropped the leveldb changes as leveldb is built with the warning options via AM_CXXFLAGS. Can be addressed separately as needed.

@Empact Empact force-pushed the isystem branch 3 times, most recently from 3f8a5d3 to 6ebba66 Compare December 18, 2018 03:37
@Empact Empact force-pushed the isystem branch 2 times, most recently from 9b50998 to d768733 Compare January 2, 2019 00:57
@fanquake
Copy link
Member

fanquake commented Jan 4, 2019

Looks like this has issues on two of the Travis linux builds (re-ran to make sure).

build:

checking miniupnpc/upnpcommands.h usability... yes
checking miniupnpc/upnpcommands.h presence... yes
checking for miniupnpc/upnpcommands.h... yes
checking for upnpDiscover in -lminiupnpc... (cached) yes
checking miniupnpc/upnperrors.h usability... yes
checking miniupnpc/upnperrors.h presence... yes
checking for miniupnpc/upnperrors.h... yes
checking for upnpDiscover in -lminiupnpc... (cached) yes
../configure: 25050: ./configure.lineno: Syntax error: redirection unexpected

build:

checking whether the Boost::System library is available... no
checking whether the Boost::Filesystem library is available... no
checking whether the Boost::Thread library is available... no
checking whether the Boost::Chrono library is available... no
checking whether the Boost::Unit_Test_Framework library is available... no
checking for dynamic linked boost test... no
checking for mismatched boost c++11 scoped enums... ok
configure: error: No working boost sleep implementation found.

@Empact Empact force-pushed the isystem branch 5 times, most recently from d508cfe to cd87913 Compare January 5, 2019 03:42
@Empact
Copy link
Contributor Author

Empact commented Jan 5, 2019

Thanks, the redirection issue was a dash incompatibility, and the boost issue was a case of -isystem/usr/include (see below). I updated any include that could resolve to /usr/include to run through the newBITCOIN_SYSTEM_INCLUDE function.

This is ready for review.

configure:29481: checking whether the Boost::System library is available
configure:29506: clang++ -std=c++11 -c  -DDEBUG_LOCKORDER -DHAVE_BUILD_INFO -D__STDC_FORMAT_MACROS -isystem/usr/include conftest.cpp >&5
In file included from conftest.cpp:76:
In file included from /usr/include/boost/system/error_code.hpp:14:
In file included from /usr/include/boost/system/config.hpp:13:
In file included from /usr/include/boost/config.hpp:57:
In file included from /usr/include/boost/config/platform/linux.hpp:15:
/usr/bin/../lib/gcc/x86_64-linux-gnu/7.3.0/../../../../include/c++/7.3.0/cstdlib:75:15: fatal error: 'stdlib.h' file not found
#include_next <stdlib.h>
              ^~~~~~~~~~
1 error generated.

https://travis-ci.org/bitcoin/bitcoin/jobs/474239063#L6175

@Empact Empact force-pushed the isystem branch 2 times, most recently from dae3db6 to 72878aa Compare January 5, 2019 08:49
Empact added 2 commits March 9, 2020 14:18
When configured with --enable-isystem.

Was necessary to split QT_INCLUDES into QT_INCLUDES and
QT_MOC_INCLUDES because moc does not understand -isystem, e.g.:

    Unknown options: isystem/usr/local/Cellar/qt/5.10.0_1/include/QtNetwork[...]

This does not convert all uses, but focuses on libraries which have triggered
warnings/errors when applying initial additional build checks: QT, Univalue, and Berkeley DB.
LevelDb requires additional measures as its code is compiled with the project warnings
via AM_CXXFLAGS.

Note -isystem should not be applied to /usr/include, see BITCOIN_SYSTEM_INCLUDE
for a helper to convert -I to -isystem with /usr/include excepted.
Or -Werror=documentation if isystem & werror are enabled.
@DrahtBot
Copy link
Contributor

🐙 This pull request conflicts with the target branch and needs rebase.

sidhujag pushed a commit to syscoin-core/syscoin that referenced this pull request Nov 10, 2020
297e098 Fix doxygen errors (Ben Woosley)

Pull request description:

  These are all the remaining errors identified via -Werror=documentation, e.g.:
  ```
    ./rpc/rawtransaction_util.h:31:13: error: parameter 'prevTxs' not found in the function declaration [-Werror,-Wdocumentation]
      * @param  prevTxs       Array of previous txns outputs that tx depends on but may not yet be in the block chain
                ^~~~~~~
    ./rpc/rawtransaction_util.h:31:13: note: did you mean 'prevTxsUnival'?
      * @param  prevTxs       Array of previous txns outputs that tx depends on but may not yet be in the block chain
                ^~~~~~~
                prevTxsUnival

    netbase.cpp:766:11: error: parameter 'outProxyConnectionFailed[out]' not found in the function declaration [-Werror,-Wdocumentation]
     * @param outProxyConnectionFailed[out] Whether or not the connection to the
              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    netbase.cpp:766:11: note: did you mean 'outProxyConnectionFailed'?
     * @param outProxyConnectionFailed[out] Whether or not the connection to the
              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
              outProxyConnectionFailed
  ```

  You can use this to run with `-Wdocumentation` yourself: bitcoin#14920

ACKs for top commit:
  laanwj:
    ACK 297e098

Tree-SHA512: a232d893b170873d923e77fa56c56a6567e7fd120b5af1f52cfeeae1093eec55621604cc80a523678f6fedc8bbb31228c4aa8dc2a630ce9ffc91525988522af7
@fanquake
Copy link
Member

fanquake commented Apr 6, 2021

Thanks for the contributions here, however I'm going to enable -Wdocumentation using a different approach.

@fanquake fanquake closed this Apr 6, 2021
@maflcko
Copy link
Member

maflcko commented Apr 6, 2021

#21613

Munkybooty pushed a commit to Munkybooty/dash that referenced this pull request Jun 9, 2022
297e098 Fix doxygen errors (Ben Woosley)

Pull request description:

  These are all the remaining errors identified via -Werror=documentation, e.g.:
  ```
    ./rpc/rawtransaction_util.h:31:13: error: parameter 'prevTxs' not found in the function declaration [-Werror,-Wdocumentation]
      * @param  prevTxs       Array of previous txns outputs that tx depends on but may not yet be in the block chain
                ^~~~~~~
    ./rpc/rawtransaction_util.h:31:13: note: did you mean 'prevTxsUnival'?
      * @param  prevTxs       Array of previous txns outputs that tx depends on but may not yet be in the block chain
                ^~~~~~~
                prevTxsUnival

    netbase.cpp:766:11: error: parameter 'outProxyConnectionFailed[out]' not found in the function declaration [-Werror,-Wdocumentation]
     * @param outProxyConnectionFailed[out] Whether or not the connection to the
              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    netbase.cpp:766:11: note: did you mean 'outProxyConnectionFailed'?
     * @param outProxyConnectionFailed[out] Whether or not the connection to the
              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
              outProxyConnectionFailed
  ```

  You can use this to run with `-Wdocumentation` yourself: bitcoin#14920

ACKs for top commit:
  laanwj:
    ACK 297e098

Tree-SHA512: a232d893b170873d923e77fa56c56a6567e7fd120b5af1f52cfeeae1093eec55621604cc80a523678f6fedc8bbb31228c4aa8dc2a630ce9ffc91525988522af7
Munkybooty pushed a commit to Munkybooty/dash that referenced this pull request Jun 21, 2022
297e098 Fix doxygen errors (Ben Woosley)

Pull request description:

  These are all the remaining errors identified via -Werror=documentation, e.g.:
  ```
    ./rpc/rawtransaction_util.h:31:13: error: parameter 'prevTxs' not found in the function declaration [-Werror,-Wdocumentation]
      * @param  prevTxs       Array of previous txns outputs that tx depends on but may not yet be in the block chain
                ^~~~~~~
    ./rpc/rawtransaction_util.h:31:13: note: did you mean 'prevTxsUnival'?
      * @param  prevTxs       Array of previous txns outputs that tx depends on but may not yet be in the block chain
                ^~~~~~~
                prevTxsUnival

    netbase.cpp:766:11: error: parameter 'outProxyConnectionFailed[out]' not found in the function declaration [-Werror,-Wdocumentation]
     * @param outProxyConnectionFailed[out] Whether or not the connection to the
              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    netbase.cpp:766:11: note: did you mean 'outProxyConnectionFailed'?
     * @param outProxyConnectionFailed[out] Whether or not the connection to the
              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
              outProxyConnectionFailed
  ```

  You can use this to run with `-Wdocumentation` yourself: bitcoin#14920

ACKs for top commit:
  laanwj:
    ACK 297e098

Tree-SHA512: a232d893b170873d923e77fa56c56a6567e7fd120b5af1f52cfeeae1093eec55621604cc80a523678f6fedc8bbb31228c4aa8dc2a630ce9ffc91525988522af7
Munkybooty pushed a commit to Munkybooty/dash that referenced this pull request Jun 25, 2022
297e098 Fix doxygen errors (Ben Woosley)

Pull request description:

  These are all the remaining errors identified via -Werror=documentation, e.g.:
  ```
    ./rpc/rawtransaction_util.h:31:13: error: parameter 'prevTxs' not found in the function declaration [-Werror,-Wdocumentation]
      * @param  prevTxs       Array of previous txns outputs that tx depends on but may not yet be in the block chain
                ^~~~~~~
    ./rpc/rawtransaction_util.h:31:13: note: did you mean 'prevTxsUnival'?
      * @param  prevTxs       Array of previous txns outputs that tx depends on but may not yet be in the block chain
                ^~~~~~~
                prevTxsUnival

    netbase.cpp:766:11: error: parameter 'outProxyConnectionFailed[out]' not found in the function declaration [-Werror,-Wdocumentation]
     * @param outProxyConnectionFailed[out] Whether or not the connection to the
              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    netbase.cpp:766:11: note: did you mean 'outProxyConnectionFailed'?
     * @param outProxyConnectionFailed[out] Whether or not the connection to the
              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
              outProxyConnectionFailed
  ```

  You can use this to run with `-Wdocumentation` yourself: bitcoin#14920

ACKs for top commit:
  laanwj:
    ACK 297e098

Tree-SHA512: a232d893b170873d923e77fa56c56a6567e7fd120b5af1f52cfeeae1093eec55621604cc80a523678f6fedc8bbb31228c4aa8dc2a630ce9ffc91525988522af7
Munkybooty pushed a commit to Munkybooty/dash that referenced this pull request Jun 28, 2022
297e098 Fix doxygen errors (Ben Woosley)

Pull request description:

  These are all the remaining errors identified via -Werror=documentation, e.g.:
  ```
    ./rpc/rawtransaction_util.h:31:13: error: parameter 'prevTxs' not found in the function declaration [-Werror,-Wdocumentation]
      * @param  prevTxs       Array of previous txns outputs that tx depends on but may not yet be in the block chain
                ^~~~~~~
    ./rpc/rawtransaction_util.h:31:13: note: did you mean 'prevTxsUnival'?
      * @param  prevTxs       Array of previous txns outputs that tx depends on but may not yet be in the block chain
                ^~~~~~~
                prevTxsUnival

    netbase.cpp:766:11: error: parameter 'outProxyConnectionFailed[out]' not found in the function declaration [-Werror,-Wdocumentation]
     * @param outProxyConnectionFailed[out] Whether or not the connection to the
              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    netbase.cpp:766:11: note: did you mean 'outProxyConnectionFailed'?
     * @param outProxyConnectionFailed[out] Whether or not the connection to the
              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
              outProxyConnectionFailed
  ```

  You can use this to run with `-Wdocumentation` yourself: bitcoin#14920

ACKs for top commit:
  laanwj:
    ACK 297e098

Tree-SHA512: a232d893b170873d923e77fa56c56a6567e7fd120b5af1f52cfeeae1093eec55621604cc80a523678f6fedc8bbb31228c4aa8dc2a630ce9ffc91525988522af7
Munkybooty pushed a commit to Munkybooty/dash that referenced this pull request Jul 6, 2022
297e098 Fix doxygen errors (Ben Woosley)

Pull request description:

  These are all the remaining errors identified via -Werror=documentation, e.g.:
  ```
    ./rpc/rawtransaction_util.h:31:13: error: parameter 'prevTxs' not found in the function declaration [-Werror,-Wdocumentation]
      * @param  prevTxs       Array of previous txns outputs that tx depends on but may not yet be in the block chain
                ^~~~~~~
    ./rpc/rawtransaction_util.h:31:13: note: did you mean 'prevTxsUnival'?
      * @param  prevTxs       Array of previous txns outputs that tx depends on but may not yet be in the block chain
                ^~~~~~~
                prevTxsUnival

    netbase.cpp:766:11: error: parameter 'outProxyConnectionFailed[out]' not found in the function declaration [-Werror,-Wdocumentation]
     * @param outProxyConnectionFailed[out] Whether or not the connection to the
              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    netbase.cpp:766:11: note: did you mean 'outProxyConnectionFailed'?
     * @param outProxyConnectionFailed[out] Whether or not the connection to the
              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
              outProxyConnectionFailed
  ```

  You can use this to run with `-Wdocumentation` yourself: bitcoin#14920

ACKs for top commit:
  laanwj:
    ACK 297e098

Tree-SHA512: a232d893b170873d923e77fa56c56a6567e7fd120b5af1f52cfeeae1093eec55621604cc80a523678f6fedc8bbb31228c4aa8dc2a630ce9ffc91525988522af7
Munkybooty pushed a commit to Munkybooty/dash that referenced this pull request Aug 3, 2022
297e098 Fix doxygen errors (Ben Woosley)

Pull request description:

  These are all the remaining errors identified via -Werror=documentation, e.g.:
  ```
    ./rpc/rawtransaction_util.h:31:13: error: parameter 'prevTxs' not found in the function declaration [-Werror,-Wdocumentation]
      * @param  prevTxs       Array of previous txns outputs that tx depends on but may not yet be in the block chain
                ^~~~~~~
    ./rpc/rawtransaction_util.h:31:13: note: did you mean 'prevTxsUnival'?
      * @param  prevTxs       Array of previous txns outputs that tx depends on but may not yet be in the block chain
                ^~~~~~~
                prevTxsUnival

    netbase.cpp:766:11: error: parameter 'outProxyConnectionFailed[out]' not found in the function declaration [-Werror,-Wdocumentation]
     * @param outProxyConnectionFailed[out] Whether or not the connection to the
              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    netbase.cpp:766:11: note: did you mean 'outProxyConnectionFailed'?
     * @param outProxyConnectionFailed[out] Whether or not the connection to the
              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
              outProxyConnectionFailed
  ```

  You can use this to run with `-Wdocumentation` yourself: bitcoin#14920

ACKs for top commit:
  laanwj:
    ACK 297e098

Tree-SHA512: a232d893b170873d923e77fa56c56a6567e7fd120b5af1f52cfeeae1093eec55621604cc80a523678f6fedc8bbb31228c4aa8dc2a630ce9ffc91525988522af7
Munkybooty pushed a commit to Munkybooty/dash that referenced this pull request Aug 16, 2022
297e098 Fix doxygen errors (Ben Woosley)

Pull request description:

  These are all the remaining errors identified via -Werror=documentation, e.g.:
  ```
    ./rpc/rawtransaction_util.h:31:13: error: parameter 'prevTxs' not found in the function declaration [-Werror,-Wdocumentation]
      * @param  prevTxs       Array of previous txns outputs that tx depends on but may not yet be in the block chain
                ^~~~~~~
    ./rpc/rawtransaction_util.h:31:13: note: did you mean 'prevTxsUnival'?
      * @param  prevTxs       Array of previous txns outputs that tx depends on but may not yet be in the block chain
                ^~~~~~~
                prevTxsUnival

    netbase.cpp:766:11: error: parameter 'outProxyConnectionFailed[out]' not found in the function declaration [-Werror,-Wdocumentation]
     * @param outProxyConnectionFailed[out] Whether or not the connection to the
              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    netbase.cpp:766:11: note: did you mean 'outProxyConnectionFailed'?
     * @param outProxyConnectionFailed[out] Whether or not the connection to the
              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
              outProxyConnectionFailed
  ```

  You can use this to run with `-Wdocumentation` yourself: bitcoin#14920

ACKs for top commit:
  laanwj:
    ACK 297e098

Tree-SHA512: a232d893b170873d923e77fa56c56a6567e7fd120b5af1f52cfeeae1093eec55621604cc80a523678f6fedc8bbb31228c4aa8dc2a630ce9ffc91525988522af7
@bitcoin bitcoin locked as resolved and limited conversation to collaborators Aug 18, 2022
@Empact Empact deleted the isystem branch October 10, 2022 20:44
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

9 participants