--- a/doc/tutorial/source/getting-started.rst	Tue May 15 22:20:41 2018 +0200
+++ a/doc/tutorial/source/getting-started.rst	Sun Jul 22 11:33:34 2018 -0700
@@ -348,6 +348,35 @@ 
 simulator did not build successfully or that it will provide wrong 
 results for the modules listed as being built.
 
+Handling build errors
++++++++++++++++++++++
+
+|ns3| releases are tested against the most recent C++ compilers available
+in the mainstream Linux and MacOS distributions at the time of the release.
+However, over time, newer distributions are released, with newer compilers,
+and these newer compilers tend to be more pedantic about warnings.  |ns3|
+configures its build to treat all warnings as errors, so it is sometimes
+the case, if you are using an older release version on a newer system,
+that a compiler warning will cause the build to fail.
+
+For instance, ns-3.28 was released prior to Fedora 28, which included
+a new major version of gcc (gcc-8).  Building ns-3.28 or older releases
+on Fedora 28, when Gtk2+ is installed, will result in an error such as:
+
+::
+
+  /usr/include/gtk-2.0/gtk/gtkfilechooserbutton.h:59:8: error: unnecessary parentheses in declaration of ‘__gtk_reserved1’ [-Werror=parentheses]
+   void (*__gtk_reserved1);
+
+In releases starting with ns-3.28.1, an option is available in Waf to work
+around these issues.  The option disables the inclusion of the '-Werror' 
+flag to g++ and clang++.  The option is '--disable-werror' and must be
+used at configure time; e.g.:
+
+::
+
+  ./waf configure --disable-werror --enable-examples --enable-tests
+
 Building with bake
 ++++++++++++++++++
 
--- a/waf-tools/cflags.py	Tue May 15 22:20:41 2018 +0200
+++ a/waf-tools/cflags.py	Sun Jul 22 11:33:34 2018 -0700
@@ -159,6 +159,9 @@ 
 	opt.add_option('--check-profile',
 		       help=('print out current build profile'),
 		       default=False, dest='check_profile', action="store_true")
+	opt.add_option('--disable-werror',
+		       help=('disable -Werror flag (warnings treated as errors'),
+		       default=False, dest='disable_werror', action="store_true")
 def configure(conf):
 	cc = conf.env['COMPILER_CC'] or None
 	cxx = conf.env['COMPILER_CXX'] or None
@@ -181,6 +184,12 @@ 
 	optimizations = compiler.get_optimization_flags(opt_level)
 	debug, debug_defs = compiler.get_debug_flags(dbg_level)
 	warnings = compiler.get_warnings_flags(warn_level)
+
+        if Options.options.disable_werror:
+                try:
+                        warnings.remove ('-Werror')
+                except ValueError:
+                        pass
 	
 	if cc and not conf.env['CCFLAGS']:
 		conf.env.append_value('CCFLAGS', optimizations)