CI: Clarify purpose of example_null, Changelog

Author: ocornut

.github/workflows/build.yml

@@ -43,7 +43,7 @@ jobs:
 
       # Not using matrix here because it would inflate job count too much. Check out and setup is done for every job and that makes build times way too long.
       - name: Build example_null (extra warnings, mingw 64-bit)
-        run: mingw32-make -C examples/example_null EXTRA_WARNINGS=1
+        run: mingw32-make -C examples/example_null WITH_EXTRA_WARNINGS=1
 
       - name: Build example_null (extra warnings, msvc 64-bit)
         shell: cmd
@@ -171,22 +171,22 @@ jobs:
     - name: Build example_null (extra warnings, gcc 32-bit)
       run: |
         make -C examples/example_null clean
-        CXXFLAGS="$CXXFLAGS -m32 -Werror" make -C examples/example_null EXTRA_WARNINGS=1
+        CXXFLAGS="$CXXFLAGS -m32 -Werror" make -C examples/example_null WITH_EXTRA_WARNINGS=1
 
     - name: Build example_null (extra warnings, gcc 64-bit)
       run: |
         make -C examples/example_null clean
-        CXXFLAGS="$CXXFLAGS -m64 -Werror" make -C examples/example_null EXTRA_WARNINGS=1
+        CXXFLAGS="$CXXFLAGS -m64 -Werror" make -C examples/example_null WITH_EXTRA_WARNINGS=1
 
     - name: Build example_null (extra warnings, clang 32-bit)
       run: |
         make -C examples/example_null clean
-        CXXFLAGS="$CXXFLAGS -m32 -Werror" CXX=clang++ make -C examples/example_null EXTRA_WARNINGS=1
+        CXXFLAGS="$CXXFLAGS -m32 -Werror" CXX=clang++ make -C examples/example_null WITH_EXTRA_WARNINGS=1
 
     - name: Build example_null (extra warnings, clang 64-bit)
       run: |
         make -C examples/example_null clean
-        CXXFLAGS="$CXXFLAGS -m64 -Werror" CXX=clang++ make -C examples/example_null EXTRA_WARNINGS=1
+        CXXFLAGS="$CXXFLAGS -m64 -Werror" CXX=clang++ make -C examples/example_null WITH_EXTRA_WARNINGS=1
 
     - name: Build example_null (freetype)
       run: |
@@ -260,7 +260,7 @@ jobs:
         brew install sdl2
 
     - name: Build example_null (extra warnings, clang 64-bit)
-      run: make -C examples/example_null EXTRA_WARNINGS=1
+      run: make -C examples/example_null WITH_EXTRA_WARNINGS=1
 
     - name: Build example_null (single file build)
       run: |
@@ -358,6 +358,6 @@ jobs:
             exit 0
           fi
           cd examples/example_null
-          pvs-studio-analyzer trace -- make EXTRA_WARNINGS=1
+          pvs-studio-analyzer trace -- make WITH_EXTRA_WARNINGS=1
           pvs-studio-analyzer analyze -e ../../imstb_rectpack.h -e ../../imstb_textedit.h -e ../../imstb_truetype.h -l ../../pvs-studio.lic -o pvs-studio.log
           plog-converter -a 'GA:1,2;OP:1' -t errorfile -w pvs-studio.log

docs/CHANGELOG.txt

@@ -61,8 +61,8 @@ Other Changes:
   in imgui_freetype.cpp (matching support in the regular code path). (#3062) [@DonKult]
 - Demo: Added black and white and color gradients to Demo>Examples>Custom Rendering.
 - CI: Added more tests on the continuous-integration server: extra warnings for Clang/GCC, building
-  SDL+Metal example, and more compile-time imconfig.h settings: disabling obsolete functions,
-  enabling 32-bit draw indices, enabling 32-bit ImWchar, disabling demo/metrics, etc. [@rokups]
+  SDL+Metal example, building imgui_freetype.cpp, more compile-time imconfig.h settings: disabling
+  obsolete functions, enabling 32-bit ImDrawIdx, enabling 32-bit ImWchar, disabling demo. [@rokups]
 - Backends: Win32: Added ImGui_ImplWin32_EnableDpiAwareness(), ImGui_ImplWin32_GetDpiScaleForHwnd(),
   ImGui_ImplWin32_GetDpiScaleForMonitor() helpers functions (backported from the docking branch).
   Those functions makes it easier for example apps to support hi-dpi features without setting up

examples/README.txt

@@ -153,7 +153,7 @@ Those will allow you to create portable applications and will solve and abstract
 ---------------------------------------
 
 Building:
-  Unfortunately in 2018 it is still tedious to create and maintain portable build files using external
+  Unfortunately in 2020 it is still tedious to create and maintain portable build files using external
   libraries (the kind we're using here to create a window and render 3D triangles) without relying on
   third party software. For most examples here I choose to provide:
    - Makefiles for Linux/OSX
@@ -164,6 +164,9 @@ Building:
   You can probably just import the imgui_impl_xxx.cpp/.h files into your own codebase or compile those
   directly with a command-line compiler.
 
+  If you are interested in using Cmake to build and links examples, see:
+    https://github.com/ocornut/imgui/pull/1713 and https://github.com/ocornut/imgui/pull/3027
+
 
 example_allegro5/
     Allegro 5 example.

examples/example_null/Makefile

@@ -2,10 +2,15 @@
 # Cross Platform Makefile
 # Compatible with MSYS2/MINGW, Ubuntu 14.04.1 and Mac OS X
 #
+# Important: This is a "null back-end" application, with no visible output or interaction!
+# This is used for testing purpose and continuous integration, and has little use for end-user.
+#
 
-EXE = example_null
-EXTRA_WARNINGS ?= 0
+# Options
+WITH_EXTRA_WARNINGS ?= 0
 WITH_FREETYPE ?= 0
+
+EXE = example_null
 SOURCES = main.cpp
 SOURCES += ../../imgui.cpp ../../imgui_demo.cpp ../../imgui_draw.cpp ../../imgui_widgets.cpp
 OBJS = $(addsuffix .o, $(basename $(notdir $(SOURCES))))
@@ -15,12 +20,13 @@ CXXFLAGS += -I../ -I../../
 CXXFLAGS += -g -Wall -Wformat
 LIBS =
 
-# We use the EXTRA_WARNINGS flag on our CI setup to eagerly catch zealous warnings
-ifeq ($(EXTRA_WARNINGS), 1)
+# We use the WITH_EXTRA_WARNINGS flag on our CI setup to eagerly catch zealous warnings
+ifeq ($(WITH_EXTRA_WARNINGS), 1)
 	CXXFLAGS += -Wno-zero-as-null-pointer-constant -Wno-double-promotion -Wno-variadic-macros
 endif
 
-# We use the WITH_FREETYPE flag on our CI setup to test misc/freetype/imgui_freetype.cpp font rasterizer
+# We use the WITH_FREETYPE flag on our CI setup to test compiling misc/freetype/imgui_freetype.cpp
+# (only supported on Linux, and note that the imgui_freetype code currently won't be executed)
 ifeq ($(WITH_FREETYPE), 1)
 	SOURCES += ../../misc/freetype/imgui_freetype.cpp
 	CXXFLAGS += $(shell pkg-config --cflags freetype2)
@@ -33,23 +39,23 @@ endif
 
 ifeq ($(UNAME_S), Linux) #LINUX
 	ECHO_MESSAGE = "Linux"
-	ifneq ($(EXTRA_WARNINGS), 0)
+	ifneq ($(WITH_EXTRA_WARNINGS), 0)
 		CXXFLAGS += -Wextra -pedantic
 	endif
 	CFLAGS = $(CXXFLAGS)
 endif
 
 ifeq ($(UNAME_S), Darwin) #APPLE
 	ECHO_MESSAGE = "Mac OS X"
-	ifneq ($(EXTRA_WARNINGS), 0)
+	ifneq ($(WITH_EXTRA_WARNINGS), 0)
 		CXXFLAGS += -Weverything -Wno-reserved-id-macro -Wno-c++98-compat-pedantic -Wno-padded -Wno-c++11-long-long
 	endif
 	CFLAGS = $(CXXFLAGS)
 endif
 
 ifeq ($(findstring MINGW,$(UNAME_S)),MINGW)
 	ECHO_MESSAGE = "MinGW"
-	ifneq ($(EXTRA_WARNINGS), 0)
+	ifneq ($(WITH_EXTRA_WARNINGS), 0)
 		CXXFLAGS += -Wextra -pedantic
 	endif
 	CFLAGS = $(CXXFLAGS)