diff --git a/README.adoc b/README.adoc
index 32b0ba0..63c18d0 100644
--- a/README.adoc
+++ b/README.adoc
@@ -12396,6 +12396,20 @@ TODO: describe the main characteristics of each platform, as of gem5 5e83d703522
 
 === gem5 internals
 
+==== gem5 Eclipse configuration
+
+In order to develop complex C++ software such as gem5, a good IDE setup is fundamental.
+
+The best setup I've reached is with Eclipse. It is not perfect, and there is a learning curve, but is worth it.
+
+I recommend the following settings, tested in Eclipse 2019.09, Ubuntu 18.04:
+
+* fix all missing stdlib headers: https://stackoverflow.com/questions/10373788/how-to-solve-unresolved-inclusion-iostream-in-a-c-file-in-eclipse-cdt/51099533#51099533
+* use spaces instead of tabs: Window, Preferences, Code Style, C/C++, Formatter, New, Edit, Tab Policy, Spaces Only
+* add to the include search path:
+** ./src/ in the source tree
+** the ISA specific build directory which contains some self-generated stuff, e.g.: out/gem5/default/build/ARM
+
 ==== gem5 Python C++ interaction
 
 The interaction uses the Python C extension interface https://docs.python.org/2/extending/extending.html interface through the pybind11 helper library: https://github.com/pybind/pybind11