From c489cd939874625dc027002a1c8596872db26cf5 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sat, 4 Sep 2021 17:17:27 +0100 Subject: [PATCH 1/4] Fix formatting and slightly update wxGTK install instructions The only real change is that the part about building wxGTK under Cygwin was removed, it wasn't very useful and shouldn't distract from other, more important, information here. --- docs/gtk/install.md | 67 +++++++++++++++------------------------------ 1 file changed, 22 insertions(+), 45 deletions(-) diff --git a/docs/gtk/install.md b/docs/gtk/install.md index 99061bf15e..4576b55813 100644 --- a/docs/gtk/install.md +++ b/docs/gtk/install.md @@ -13,38 +13,31 @@ The simplest case {#gtk_simple} If you compile wxWidgets on Linux for the first time and don't like to read install instructions just do the following in wxWidgets directory: - > mkdir buildgtk - > cd buildgtk - > ../configure --with-gtk - > make - > sudo make install - > sudo ldconfig + $ mkdir buildgtk + $ cd buildgtk + $ ../configure --with-gtk + $ make + $ sudo make install + $ sudo ldconfig -[if you get "ldconfig: command not found", try using "/sbin/ldconfig"] +(if you get "ldconfig: command not found", try using `/sbin/ldconfig`) -If you don't do the 'make install' part, you can still use the libraries from -the buildgtk directory, but they may not be available to other users. - -If you want to remove wxWidgets on Unix you can do this: - - > sudo make uninstall - > sudo ldconfig +If you don't do the `make install` part, you can still use the libraries from +the `buildgtk` directory, but they may not be available to other users. Note that by default, GTK 3 is used. GTK 2 can be specified -with --with-gtk=2. +with `--with-gtk=2` configure option. -If you use CMake, please see @ref overview_cmake for +If you want to use CMake, please see @ref overview_cmake for building wxWidgets using it. Troubleshooting {#gtk_errors_simple} --------------- -IMPORTANT NOTE: - - When sending bug reports tell us what version of wxWidgets you are - using (including the beta) and what compiler on what system. One - example: wxGTK 3.0.5, GCC 9.3.1, Fedora 31. +*IMPORTANT NOTE:* When sending bug reports tell us the exact version of +wxWidgets you are using as well as what compiler on what system. One example: +wxGTK 3.0.5, GCC 9.3.1, Fedora 31. For any configure errors: please look at `config.log` file which was generated during configure run, it usually contains some useful information. @@ -76,20 +69,6 @@ Now create your super-application myfoo.cpp and compile anywhere with -Building wxGTK on Cygwin {#gtk_cygwin} --------------------------- - -The normal build instructions should work fine on Cygwin. The one difference -with Cygwin is that when using the "--enable-shared" configure option (which -is the default) the API is exported explicitly using `__declspec(dllexport)` -rather than all global symbols being available. - -This shouldn't make a difference using the library and should be a little -more efficient. However if an export attribute has been missed somewhere you -will see linking errors. If this happens then you can work around the -problem by setting `LDFLAGS=-Wl,--export-all-symbols`. Please also let us know -about it on the wx-dev mailing list. - Configure options {#gtk_options} ----------------- @@ -257,7 +236,7 @@ Then you may install the library and its header files under have to perform the following command as root, using either `su` or `sudo`: - make install + $ make install After installing, you can run `make clean` in the original directory or just remove it entirely if you don't plan to build @@ -283,17 +262,15 @@ in the following way (note that if you are copying and pasting this into your makefile, the leading spaces must be replaced by a `TAB` character): -```make -program: program.o - $(CXX) -o program program.o `wx-config --libs` + program: program.o + $(CXX) -o program program.o `wx-config --libs` -program.o: program.cpp - $(CXX) `wx-config --cxxflags` -c program.cpp -o program.o + program.o: program.cpp + $(CXX) `wx-config --cxxflags` -c program.cpp -o program.o -clean: - $(RM) program.o program -.PHONY: clean -``` + clean: + $(RM) program.o program + .PHONY: clean If your application uses only some of wxWidgets libraries, you can specify required libraries when running wx-config. For example, From 45f7ec9bdba9972ba974426f8cf1a2ed8b9d8b48 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sat, 4 Sep 2021 17:40:18 +0100 Subject: [PATCH 2/4] Add "prerequisites" section to GTK installation instructions List the required packages in Debian/Ubuntu and Fedora/CentOS. --- docs/gtk/install.md | 51 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 46 insertions(+), 5 deletions(-) diff --git a/docs/gtk/install.md b/docs/gtk/install.md index 4576b55813..06e0f566c4 100644 --- a/docs/gtk/install.md +++ b/docs/gtk/install.md @@ -32,6 +32,42 @@ If you want to use CMake, please see @ref overview_cmake for building wxWidgets using it. +Prerequisites {#gtk_prereq} +------------- + +To build wxWidgets, you need to have a number of libraries on your system. +While all of them may be compiled from source, under Linux systems it is much +more common to install the development packages containing the headers and +library files. + +At the very least, you will need GTK libraries themselves. Unfortunately the +exact package names differ between different Linux distributions, but for +Debian and Debian-based distribution these libraries are part of `libgtk-3-dev` +package, while in Fedora and other RPM-based distributions the same package is +known as `gtk3-devel`. + +For OpenGL support, you need `libgl1-mesa-dev` and `libglu1-mesa-dev` packages +under Debian and `mesa-libGL-devel` and `mesa-libGLU-devel` under Fedora. For +EGL support, `libegl1-mesa-dev` or `mesa-libEGL-devel` is needed. + +wxMediaCtrl implementation requires GStreamer and its plugins development +packages, i.e. either `libgstreamer-plugins-baseVERSION-dev` or +`gstreamerVERSION-plugins-base-devel`, where `VERSION` should be 1.0, but 0.10 +is still supported as well for compatibility with old systems. + +wxWebRequest requites libcurl development package, e.g. `libcurl4-openssl-dev` +or `libcurl-devel`. + +wxWebView requires `libwebkit2gtk-4.0-dev` under Debian and `webkit2gtk3-devel` +under Fedora. + +For the different image format libraries (PNG, JPEG, TIFF) as well as zlib, you +may install the corresponding `libNAME-dev` or `-devel` libraries or use the +built-in versions of them, i.e. the same libraries compiled as part of +wxWidgets, instead if you prefer. + + + Troubleshooting {#gtk_errors_simple} --------------- @@ -99,20 +135,25 @@ of libraries to build: the default since wxWidgets 2.5.0). Options for third party dependencies: wxWidgets may use other -libraries present on the current system. For some of these -libraries, wxWidgets also provides built-in versions, that can be +libraries present on the current system, see the @ref gtk_prereq +"prerequisites section above". For some of these libraries, +wxWidgets also provides built-in versions, that can be linked into wx libraries themselves, which can be useful to -minimize external dependencies. +minimize external dependencies. By default, system versions will be +used if available, but `--with-xxx=builtin` configure option may be +used to override this. --disable-sys-libs Don't use system libraries when there is a built-in version included in wxWidgets. + This is equivalent to using --with-xxx=builtin + for all libraries that have built-in versions. Note that other system libraries can, and typically will, still be used if found. --without-libpng Disables PNG image format code. - Don't use libpng (although GTK - itself still uses it). + Don't use neither the system nor the builtin + libpng (although GTK itself still uses it). --without-libjpeg Disables JPEG image format code. Don't use libjpeg. From 91923dc3f12c3ef8a4cad7181fa2b9f9f151b282 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sat, 4 Sep 2021 17:47:19 +0100 Subject: [PATCH 3/4] Reformat configure options description No changes in contents, just use a list for configure options rather than preformatted text block. --- docs/gtk/install.md | 149 +++++++++++++++++++++----------------------- 1 file changed, 71 insertions(+), 78 deletions(-) diff --git a/docs/gtk/install.md b/docs/gtk/install.md index 06e0f566c4..88930f2819 100644 --- a/docs/gtk/install.md +++ b/docs/gtk/install.md @@ -127,12 +127,12 @@ more information). The following options can be used to specify the kind and number of libraries to build: - --disable-shared Do not create shared libraries, but - build static libraries instead. + * `--disable-shared` \n + Do not create shared libraries, but build static libraries instead. - --enable-monolithic Build wxWidgets as single library instead - of as several smaller libraries (which is - the default since wxWidgets 2.5.0). + * `--enable-monolithic` \n + Build wxWidgets as single library instead of as several smaller libraries + (which is the default since wxWidgets 2.5.0). Options for third party dependencies: wxWidgets may use other libraries present on the current system, see the @ref gtk_prereq @@ -143,121 +143,114 @@ minimize external dependencies. By default, system versions will be used if available, but `--with-xxx=builtin` configure option may be used to override this. - --disable-sys-libs Don't use system libraries when there is - a built-in version included in wxWidgets. - This is equivalent to using --with-xxx=builtin - for all libraries that have built-in versions. - Note that other system libraries can, - and typically will, still be used if - found. + * `--disable-sys-libs` \n + Don't use system libraries when there is a built-in version included in + wxWidgets. This is equivalent to using --with-xxx=builtin for all libraries + that have built-in versions. Note that other system libraries can, and + typically will, still be used if found. - --without-libpng Disables PNG image format code. - Don't use neither the system nor the builtin - libpng (although GTK itself still uses it). + * `--without-libpng` \n + Disables PNG image format code. Don't use neither the system nor the builtin + libpng (although GTK itself still uses it). - --without-libjpeg Disables JPEG image format code. - Don't use libjpeg. + * `--without-libjpeg` \n + Disables JPEG image format code. Don't use libjpeg. - --without-libtiff Disables TIFF image format code. - Don't use libtiff. + * `--without-libtiff` \n + Disables TIFF image format code. Don't use libtiff. - --without-expat Disable XML classes based on Expat parser. - Don't use expat library. + * `--without-expat` \n + Disable XML classes based on Expat parser. Don't use expat library. - --without-liblzma Disable LZMA compression support. - Don't use liblzma. + * `--without-liblzma` \n + Disable LZMA compression support. Don't use liblzma. - --without-libcurl Don't use libcurl even if it's available. - Disables wxWebRequest. + * `--without-libcurl` \n + Don't use libcurl even if it's available. Disables wxWebRequest. - --without-opengl Disable OpenGL integration with wxGLCanvas. - Don't use OpenGL or EGL libraries. + * `--without-opengl` \n + Disable OpenGL integration with wxGLCanvas. Don't use OpenGL or EGL libraries. - --disable-glcanvasegl Disable EGL support even if it is available - (it would be used if it is, by default). + * `--disable-glcanvasegl` \n + Disable EGL support even if it is available (it would be used if it is, by default). - --disable-mediactrl Disable wxMediaCtrl. - Don't use GStreamer libraries. + * `--disable-mediactrl` \n + Disable wxMediaCtrl. Don't use GStreamer libraries. - --disable-webview Disable wxWebView. - Don't use webkit2gtk and its multiple - dependencies. + * `--disable-webview` \n + Disable wxWebView. Don't use webkit2gtk and its multiple dependencies. Normally, you won't have to choose a toolkit, because configure defaults to wxGTK anyhow. However you need to use this option to explicitly specify the version of GTK to use, e.g.: - --with-gtk=3 Use GTK 3. Default. - --with-gtk=2 Use GTK 2. - --with-gtk=1 Use GTK 1.2. Obsolete. + * `--with-gtk=3` \n Use GTK 3. Default. + * `--with-gtk=2` \n Use GTK 2. + * `--with-gtk=1` \n Use GTK 1.2. Obsolete. Some other general compilation options: - --disable-optimise Do not optimise the code. Can be useful - for debugging but shouldn't be used - for production builds. + * `--disable-optimise` \n + Do not optimise the code. Can be useful for debugging but shouldn't be used + for production builds. - --disable-unicode Disable Unicode support. Not recommended. + * `--disable-unicode` \n + Disable Unicode support. Not recommended. - --enable-no_rtti Enable compilation without creation of - C++ RTTI information in object files. - This will speed-up compilation and reduce - binary size. + * `--enable-no_rtti` \n + Enable compilation without creation of C++ RTTI information in object files. + This will speed-up compilation and reduce binary size. - --enable-no_exceptions Enable compilation without creation of - C++ exception information in object files. - This will speed-up compilation and reduce - binary size. + * `--enable-no_exceptions` \n + Enable compilation without creation of C++ exception information in object + files. This will speed-up compilation and reduce binary size. - --enable-debug_info Add debug info to object files and - executables for use with debuggers - such as gdb (or its many frontends). + * `--enable-debug_info` \n + Add debug info to object files and executables for use with debuggers such + as gdb (or its many frontends). - --enable-debug_flag Define __DEBUG__ and __WXDEBUG__ when - compiling. This enable wxWidgets' very - useful internal debugging tricks (such - as automatically reporting illegal calls) - to work. Note that program and library - must be compiled with the same debug - options. + * `--enable-debug_flag` \n + Define __DEBUG__ and __WXDEBUG__ when compiling. This enable wxWidgets' very + useful internal debugging tricks (such as automatically reporting illegal + calls) to work. Note that program and library must be compiled with the same + debug options. - --enable-debug Same as --enable-debug_info and - --enable-debug_flag together. Unless you have - some very specific needs, you should use this - option instead of --enable-debug_info/flag ones - separately. + * `--enable-debug` \n + Same as --enable-debug_info and --enable-debug_flag together. Unless you + have some very specific needs, you should use this option instead of + --enable-debug_info/flag ones separately. To reduce the final libraries (or executables, when linking statically) size, many wxWidgets features may be disabled. Here is a list of some of them: - --disable-pnm Disables PNM image format code. + * `--disable-pnm` \n Disables PNM image format code. - --disable-gif Disables GIF image format code. + * `--disable-gif` \n Disables GIF image format code. - --disable-pcx Disables PCX image format code. + * `--disable-pcx` \n Disables PCX image format code. - --disable-iff Disables IFF image format code. + * `--disable-iff` \n Disables IFF image format code. - --disable-resources Disables the use of *.wxr type resources. + * `--disable-resources` \n Disables the use of *.wxr type resources. - --disable-threads Disables threads. Will also disable sockets. + * `--disable-threads` \n Disables threads. Will also disable sockets. - --disable-sockets Disables sockets. + * `--disable-sockets` \n Disables sockets. - --disable-dnd Disables Drag'n'Drop. + * `--disable-dnd` \n Disables Drag'n'Drop. - --disable-clipboard Disables Clipboard. + * `--disable-clipboard` \n Disables Clipboard. - --disable-streams Disables the wxStream classes. + * `--disable-streams` \n Disables the wxStream classes. - --disable-file Disables the wxFile class. + * `--disable-file` \n Disables the wxFile class. - --disable-textfile Disables the wxTextFile class. + * `--disable-textfile` \n Disables the wxTextFile class. - --disable-intl Disables the internationalisation. + * `--disable-intl` \n Disables the internationalisation. - --disable-validators Disables validators. + * `--disable-validators` \n Disables validators. Please remember that the full list of options can be seen in `configure --help` output. From e38e08952560b9eebd547e8919e12ec3dc193085 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sat, 4 Sep 2021 17:50:29 +0100 Subject: [PATCH 4/4] Update configure --enable-debug[_flag] options description Don't say that the application needs to be compiled with the same __WXDEBUG__ value, as this is not true since 3.0 days. Also link the debugging overview. --- docs/gtk/install.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/gtk/install.md b/docs/gtk/install.md index 88930f2819..4c53e5412e 100644 --- a/docs/gtk/install.md +++ b/docs/gtk/install.md @@ -210,15 +210,13 @@ Some other general compilation options: as gdb (or its many frontends). * `--enable-debug_flag` \n - Define __DEBUG__ and __WXDEBUG__ when compiling. This enable wxWidgets' very - useful internal debugging tricks (such as automatically reporting illegal - calls) to work. Note that program and library must be compiled with the same - debug options. + Enable internal debugging checks, that are very useful during development + and allow to diagnose illegal parameters to wxWidgets functions as long as + the application doesn't predefine `NDEBUG` (see @ref overview_debugging). * `--enable-debug` \n - Same as --enable-debug_info and --enable-debug_flag together. Unless you - have some very specific needs, you should use this option instead of - --enable-debug_info/flag ones separately. + Same as `--enable-debug_info` and `--enable-debug_flag` together. Typically + this is the option you want to use. To reduce the final libraries (or executables, when linking statically) size, many wxWidgets features may be disabled. Here