Add new global header wireshark.h with guideline

Remove ws_diag_control.h from config.h because that was a workaround
for the lack of a public global header. Fix the resultant build errors.

CMakeLists.txt

@@ -3429,6 +3429,7 @@ set(SHARK_PUBLIC_HEADERS
 	ws_diag_control.h
 	ws_log_defs.h
 	ws_symbol_export.h
+	wireshark.h
 	${CMAKE_BINARY_DIR}/ws_version.h
 )
 

capture/iface_monitor.c

@@ -8,13 +8,11 @@
  * SPDX-License-Identifier: GPL-2.0-or-later
  */
 
-#include <config.h>
+#include "config.h"
+#include "iface_monitor.h"
 
 #ifdef HAVE_LIBPCAP
 
-#include <capture/iface_monitor.h>
-#include "ws_attributes.h"
-
 #if defined(HAVE_LIBNL)
 
 /*

capture/iface_monitor.h

@@ -10,6 +10,8 @@
 #ifndef IFACE_MONITOR_H
 #define IFACE_MONITOR_H
 
+#include <wireshark.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif /* __cplusplus */

capture/ws80211_utils.c

@@ -12,15 +12,14 @@ Copyright (c) 2008-2009		Luis R. Rodriguez
 SPDX-License-Identifier: ISC
 */
 
-#include <config.h>
+#include "config.h"
+#include "ws80211_utils.h"
 
 #include <stdio.h>
 
 #include <glib.h>
 #include <glib/gstdio.h>
 
-#include "ws80211_utils.h"
-
 #if defined(HAVE_LIBNL) && defined(HAVE_NL80211)
 #include <string.h>
 #include <errno.h>

capture/ws80211_utils.h

@@ -11,7 +11,7 @@
 #ifndef __WS80211_UTILS_H__
 #define __WS80211_UTILS_H__
 
-#include "ws_attributes.h"
+#include <wireshark.h>
 
 #ifdef __cplusplus
 extern "C" {

cmakeconfig.h.in

@@ -316,7 +316,6 @@
 #  endif
 #endif
 
-#include <ws_diag_control.h>
 #include <ws_log_defs.h>
 
 #endif /* __CONFIG_H__ */

doc/README.developer

@@ -757,6 +757,84 @@ so your code won't even compile when warnings occur.
 
 7. General observations about architecture
 
+7.1 The global header "wireshark.h"
+
+You should include the global header <wireshark.h> in your code. However
+there are some things to keep in mind when using it and especially
+if you are considering modifying it.
+
+** wireshark.h needs to be minimal: for efficiency reasons, to reduce the
+error surface and because every time this header changes everything must be
+rebuilt. Consider carefully if another header/module should be included
+globally with every project file and exported as public header.
+
+** No configuration: configuration is specific to the build environment
+and target machine. wireshark.h must not depend on that.
+
+** Only wireshark system headers allowed: plugins use this header and
+cannot depend on any header (even indirectly) that is not installed on the
+target system.
+
+** Only global definitions allowed: for example it is acceptable to include
+'wsutil' headers in wireshark.h because every component of Wireshark is allowed
+to depend on wsutil. wiretap is not acceptable because we cannot introduce
+dependencies on wiretap globally (and wireshark.h must be usable everywhere).
+
+7.2 Best practices using headers
+
+C files can be categorized in three types: source files, private headers and
+public headers.
+
+A module "foobar" can have only a private header, only a public header, or
+both. If it's only one it is named "foobar.h" in both cases. If it is both they
+are named "foobar-int.h" and "foobar.h" respectively.
+
+In general the order of #include's for a C module source files (foobar.c),
+assuming foobar implements any kind of interface should be:
+
+  #include "config.h"
+  #define WS_LOG_DOMAIN "mydomain"
+  #include "foobar-int.h"
+
+  followed by <system headers>
+  followed by <wireshark public headers>
+  followed by <wireshark private headers>
+
+For header files (private and public) config.h must NOT be included. A public
+header file (foobar.h) looks like this:
+
+  #ifndef __FOOBAR_H__
+  #define __FOOBAR_H__
+  #include <wireshark.h>
+  followed by <system headers>
+  followed by <wireshark public headers>
+
+  #ifdef __cplusplus
+  extern "C" { 
+  #endif
+  (declarations)
+  #ifdef __cplusplus
+  }
+  #endif
+  #endif /* FOOBAR_H */
+
+A private header (foobar-int.h) is the public header plus the declarations
+with private scope:
+
+  #ifndef __FOOBAR_INT_H__
+  #define __FOOBAR_INT_H__
+  #include "foobar.h"
+  followed by <system headers>
+  followed by <wireshark public headers>
+  followed by <wireshark private headers>
+  (etc.)
+
+Again if there are only public or private declarations the name foobar-int.h
+is not used. The macro symbol WS_LOG_DOMAIN can be defined in source files or
+private headers as long as it comes before wireshark.h.
+
+7.3 libwireshark is not a single monolithic entity
+
 One day we might conceivably wish to load dissectors on demand and do other
 more sophisticated kinds of unit test. Plus other scenarios not immediately
 obvious. For this to be possible it is important that the code in epan/ does

doc/plugins.example/hello.c

@@ -10,14 +10,10 @@
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
-
 #define WS_BUILD_DLL
-
+#include <wireshark.h>
 #include <epan/packet.h>
 #include <epan/proto.h>
-#include <ws_attributes.h>
-#include <ws_symbol_export.h>
-#include <ws_version.h>
 
 #ifndef VERSION
 #define VERSION "0.0.0"

epan/dtd_parse.l

@@ -1,6 +1,7 @@
 %top {
 /* Include this before everything else, for various large-file definitions */
 #include "config.h"
+#include <wireshark.h>
 }
 
 /*

epan/dtd_preparse.l

@@ -1,6 +1,7 @@
 %top {
 /* Include this before everything else, for various large-file definitions */
 #include "config.h"
+#include <wireshark.h>
 }
 
 /*

epan/protobuf_lang_scanner.l

@@ -1,6 +1,7 @@
 %top {
 /* Include this before everything else, for various large-file definitions */
 #include "config.h"
+#include <wireshark.h>
 }
 
 /*
@@ -57,7 +58,6 @@
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
-#include <glib.h>
 #include "protobuf_lang_tree.h"
 #include "protobuf_lang_parser.h"
 

epan/uat_load.l

@@ -1,6 +1,7 @@
 %top {
 /* Include this before everything else, for various large-file definitions */
 #include "config.h"
+#include <wireshark.h>
 }
 
 /*

extcap/dpauxmon.c

@@ -13,6 +13,8 @@
 #include "config.h"
 #define WS_LOG_DOMAIN "dpauxmon"
 
+#include <wireshark.h>
+
 #include "extcap-base.h"
 
 #include <wsutil/strtoi.h>

text2pcap-scanner.l

@@ -54,6 +54,8 @@
 
 #include "text2pcap.h"
 
+#include <wireshark.h>
+
 /*
  * Disable diagnostics in the code generated by Flex.
  */

ui/text_import.c

@@ -89,6 +89,7 @@
 #    define _XOPEN_SOURCE 600
 #  endif
 #endif
+#include "text_import.h"
 
 /*
  * Defining _XOPEN_SOURCE is needed on some platforms, e.g. platforms
@@ -127,7 +128,6 @@
 # include "wsutil/strptime.h"
 #endif
 
-#include "text_import.h"
 #include "text_import_scanner.h"
 #include "text_import_scanner_lex.h"
 #include "text_import_regex.h"

ui/text_import.h

@@ -17,7 +17,8 @@
 #ifndef __TEXT_IMPORT_H__
 #define __TEXT_IMPORT_H__
 
-#include <glib.h>
+#include <stdio.h>
+#include <wireshark.h>
 
 #include <wiretap/wtap.h>
 

ui/text_import_scanner.l

@@ -3,6 +3,7 @@
 %top {
 /* Include this before everything else, for various large-file definitions */
 #include "config.h"
+#include <wireshark.h>
 }
 
 /*

wireshark.h

@@ -0,0 +1,62 @@
+/* wireshark.h
+ * Global public header with minimally available wireshark API
+ *
+ * Wireshark - Network traffic analyzer
+ * By Gerald Combs <gerald@wireshark.org>
+ * Copyright 1998 Gerald Combs
+ *
+ * SPDX-License-Identifier: GPL-2.0-or-later
+ */
+
+#ifndef __WIRESHARK_H__
+#define __WIRESHARK_H__
+
+/*
+ * This header can be included in any file, header or source, public or private.
+ * It is strongly recommended to be always included to provide macros that are
+ * required for the project and a consistent minimum set of interfaces that are
+ * always guaranteed to be available. There is no need to include <glib.h>
+ * directly, this header should replace it.
+ *
+ * Other public headers provided here should be minimal, with stable interfaces
+ * and have only global declarations.
+ *
+ * Everytime this header changes everything must be rebuilt so consider carefully
+ * if the other project headers included here should really have global scope.
+ *
+ * See README.developer for a more in-depth guide.
+ */
+
+/* System headers.*/
+#include <stdint.h>
+#include <stdbool.h>
+#include <glib.h>
+
+/*
+ * Project headers and definitions.
+ *
+ * Only public headers and symbols can be included here. Nothing related
+ * with configuration.
+ */
+#include <ws_attributes.h>
+#include <ws_compiler_tests.h>
+#include <ws_diag_control.h>
+#include <ws_symbol_export.h>
+#include <ws_version.h>
+
+#include <wsutil/ws_assert.h>
+
+#endif /* __WIRESHARK_H__ */
+
+/*
+ * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
+ *
+ * Local variables:
+ * c-basic-offset: 4
+ * tab-width: 8
+ * indent-tabs-mode: nil
+ * End:
+ *
+ * vi: set shiftwidth=4 tabstop=8 expandtab:
+ * :indentSize=4:tabSize=8:noTabs=true:
+ */

wiretap/busmaster_parser.lemon

@@ -14,6 +14,7 @@
 #include "config.h"
 #include <assert.h>
 #include <string.h>
+#include <wireshark.h>
 #include <wiretap/file_wrappers.h>
 #include "busmaster_priv.h"
 

wiretap/file_wrappers.c

@@ -14,15 +14,15 @@
  *
  */
 
-#include <config.h>
+#include "config.h"
+#include "file_wrappers.h"
 
 #include <assert.h>
 #include <errno.h>
 #include <string.h>
 #include "wtap-int.h"
-#include "file_wrappers.h"
+
 #include <wsutil/file_util.h>
-#include <wsutil/ws_assert.h>
 
 #ifdef HAVE_ZLIB
 #define ZLIB_CONST

wiretap/file_wrappers.h

@@ -9,10 +9,9 @@
 #ifndef __WTAP_FILE_WRAPPERS_H__
 #define __WTAP_FILE_WRAPPERS_H__
 
-#include <glib.h>
+#include <wireshark.h>
 #include "wtap.h"
 #include <wsutil/file_util.h>
-#include "ws_symbol_export.h"
 
 extern FILE_T file_open(const char *path);
 extern FILE_T file_fdopen(int fildes);

wsutil/plugins.c

@@ -10,6 +10,7 @@
 
 #include "config.h"
 #define WS_LOG_DOMAIN LOG_DOMAIN_WSUTIL
+#include "plugins.h"
 
 #include <time.h>
 
@@ -18,7 +19,6 @@
 #include <string.h>
 #include <errno.h>
 
-#include <glib.h>
 #include <gmodule.h>
 
 #include <wsutil/filesystem.h>
@@ -27,9 +27,6 @@
 #include <wsutil/report_message.h>
 #include <wsutil/wslog.h>
 
-#include <wsutil/plugins.h>
-#include <wsutil/ws_assert.h>
-
 typedef struct _plugin {
     GModule        *handle;       /* handle returned by g_module_open */
     gchar          *name;         /* plugin name */

wsutil/plugins.h

@@ -11,10 +11,8 @@
 #ifndef __PLUGINS_H__
 #define __PLUGINS_H__
 
-#include <glib.h>
-
+#include <wireshark.h>
 #include <gmodule.h>
-#include "ws_symbol_export.h"
 
 #ifdef __cplusplus
 extern "C" {

wsutil/str_util.c

@@ -8,10 +8,8 @@
  * SPDX-License-Identifier: GPL-2.0-or-later
  */
 
-#include <config.h>
-
+#include "config.h"
 #include "str_util.h"
-#include <wsutil/ws_assert.h>
 
 int
 ws_xton(char ch)

wsutil/str_util.h

@@ -11,9 +11,7 @@
 #ifndef __STR_UTIL_H__
 #define __STR_UTIL_H__
 
-#include <glib.h>
-#include "ws_symbol_export.h"
-
+#include <wireshark.h>
 #include <wsutil/wmem/wmem.h>
 
 #ifdef __cplusplus

wsutil/wslog.h

@@ -11,17 +11,16 @@
 #ifndef __WSLOG_H__
 #define __WSLOG_H__
 
-#include <ws_symbol_export.h>
-#include <ws_attributes.h>
 #include <glib.h>
 #include <stdio.h>
 #include <time.h>
 #include <stdarg.h>
 
-#include <wsutil/wmem/wmem.h>
-
+#include <wireshark.h>
 #include <ws_log_defs.h>
 
+#include <wsutil/wmem/wmem.h>
+
 #ifdef WS_LOG_DOMAIN
 #define _LOG_DOMAIN WS_LOG_DOMAIN
 #else