From 80f33c0c8c406f6b081ac09aba97075c3bb276b3 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sun, 11 Apr 2021 13:14:27 +0200 Subject: [PATCH 1/5] Order topics of "Starting" section in more logical order In particular, put "notes" at the end of this section instead of the very beginning as it's definitely not the most important part here. --- docs/doxygen/mainpages/topics.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/doxygen/mainpages/topics.h b/docs/doxygen/mainpages/topics.h index ceb5b4c6ea..59aea014ab 100644 --- a/docs/doxygen/mainpages/topics.h +++ b/docs/doxygen/mainpages/topics.h @@ -18,10 +18,10 @@ topics related to building applications with wxWidgets. @section page_topics_starting Starting with wxWidgets -@li @subpage overview_referencenotes -@li @subpage overview_roughguide @li @subpage overview_helloworld +@li @subpage overview_roughguide @li @subpage overview_cmake +@li @subpage overview_referencenotes @section page_topics_programming Important wxWidgets Topics From c5ab151a72c5baaea276d6ece0436a99e56187a2 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sun, 11 Apr 2021 13:15:36 +0200 Subject: [PATCH 2/5] Rename and reorder "Important wxWidgets Topics" section Events and sizing is more important than Unicode or i18n, so put them first. Also "important" doesn't really mean anything, so use a hopefully more clear section name. --- docs/doxygen/mainpages/topics.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/doxygen/mainpages/topics.h b/docs/doxygen/mainpages/topics.h index 59aea014ab..b1480afcdc 100644 --- a/docs/doxygen/mainpages/topics.h +++ b/docs/doxygen/mainpages/topics.h @@ -23,15 +23,15 @@ topics related to building applications with wxWidgets. @li @subpage overview_cmake @li @subpage overview_referencenotes -@section page_topics_programming Important wxWidgets Topics +@section page_topics_programming Conceptual Overviews @li @subpage overview_app -@li @subpage overview_unicode -@li @subpage overview_i18n @li @subpage overview_events @li @subpage overview_windowsizing @li @subpage overview_windowids @li @subpage overview_log +@li @subpage overview_unicode +@li @subpage overview_i18n @section page_topics_nongui Non-GUI Classes From cf2bb21885a8ccf76940e9b5fda158f292b66f64 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sun, 11 Apr 2021 13:24:33 +0200 Subject: [PATCH 3/5] Add a note about using ranged-based for loop with wxString It is surprising that "for (auto& c: s)" doesn't compile, so document this and propose a replacement. Do not document the fact that "for (auto c: s)" actually allows to modify the string via "c" (which is still wxUniCharRef) as this is probably just going to confuse people more than help. --- docs/doxygen/overviews/unicode.h | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/doxygen/overviews/unicode.h b/docs/doxygen/overviews/unicode.h index 6712e5476c..5b323204d2 100644 --- a/docs/doxygen/overviews/unicode.h +++ b/docs/doxygen/overviews/unicode.h @@ -255,6 +255,11 @@ n: string iterators instead if possible or replace this expression with @code s.c_str() + n @endcode otherwise. + - When using C++11 range-based for loop, the natural construct for iterating + over wxString @code for ( auto& ch: s ) @endcode doesn't compile because of + the unusual iterator type and @code for ( wxUniCharRef ch: s ) @endcode + needs to be used instead. + Another class of problems is related to the fact that the value returned by @c c_str() itself is also not just a pointer to a buffer but a value of helper class wxCStrData which is implicitly convertible to both narrow and wide From b963ce05837bb4e5a264dc9329671124c31e3cfe Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sun, 11 Apr 2021 14:17:54 +0200 Subject: [PATCH 4/5] Add new "Installation" page to the manual Currently this simply links to the existing port-specific installation instructions, but this should provide a less confusing and more prominent entry point than the existing topics. --- docs/doxygen/mainpages/topics.h | 2 +- docs/doxygen/overviews/helloworld.h | 3 ++ docs/doxygen/overviews/install.md | 81 +++++++++++++++++++++++++++++ 3 files changed, 85 insertions(+), 1 deletion(-) create mode 100644 docs/doxygen/overviews/install.md diff --git a/docs/doxygen/mainpages/topics.h b/docs/doxygen/mainpages/topics.h index b1480afcdc..af310984e2 100644 --- a/docs/doxygen/mainpages/topics.h +++ b/docs/doxygen/mainpages/topics.h @@ -18,9 +18,9 @@ topics related to building applications with wxWidgets. @section page_topics_starting Starting with wxWidgets +@li @subpage overview_install @li @subpage overview_helloworld @li @subpage overview_roughguide -@li @subpage overview_cmake @li @subpage overview_referencenotes @section page_topics_programming Conceptual Overviews diff --git a/docs/doxygen/overviews/helloworld.h b/docs/doxygen/overviews/helloworld.h index fa6dea6405..2886905a2d 100644 --- a/docs/doxygen/overviews/helloworld.h +++ b/docs/doxygen/overviews/helloworld.h @@ -14,6 +14,9 @@ This page shows a very simple wxWidgets program that can be used as a skeleton for your own code. While it does nothing very useful, it introduces a couple of important concepts and explains how to write a working wxWidgets application. +Trying building and running this application is also a good way of checking +that wxWidgets is correctly installed on your system. And if you haven't +installed wxWidgets yet, please @ref overview_install "do it first". Note that this simple example creates the UI entirely from C++ code which is fine for a simple example, but more realistic examples will typically define diff --git a/docs/doxygen/overviews/install.md b/docs/doxygen/overviews/install.md new file mode 100644 index 0000000000..ab47e4e99e --- /dev/null +++ b/docs/doxygen/overviews/install.md @@ -0,0 +1,81 @@ +Installing wxWidgets {#overview_install} +==================== + +wxWidgets headers and libraries must be available in order to build the +applications using it, so the first step when starting to use wxWidgets is to +install it. This can be done, for all platforms and library versions, by +building wxWidgets from sources, but for the most common platforms pre-built +binaries of the libraries are also provided, so the first decision to make is +whether to use these binaries or build the library yourself. Building the +libraries yourself allows you to compile the latest version using exactly the +options you need, and so is the most flexible solution, but using the binaries +may be simpler and faster -- the choice is yours, just follow the instructions +in the corresponding section below depending on the approach you prefer. Of +course, you only need to do one _or_ the other, _not_ both. + + +Using Binaries +-------------- + +How to install binaries depends on your platform: + +- For Microsoft Windows (MSW), wxWidgets project provides official binaries + on the [Downloads page](http://www.wxwidgets.org/downloads/), please see + the [instructions for using them](@ref plat_msw_binaries). + +- For Linux, and other free Unix-like systems, wxWidgets packages are available + in system repositories under the name "wxGTK". Note that to develop + applications using wxWidgets you may need to install the "development" + packages and not just the libraries needed for running the applications using + wxWidgets. For example, under Debian and Debian-derived systems such as + Ubuntu, you need to run `apt get libwxgtkX.Y-dev`. + +- For macOS, wxWidgets is available in third-party package managers such as + [brew][1] or [MacPorts][2], and you can install them in the usual way. + +[1]: https://brew.sh/ +[2]: https://www.macports.org/ + + +Additionally, some third-party C++ package managers also provide wxWidgets +binaries. For example, please see [this post][3] for the instructions about +using [vcpkg][4] C++ package manager for installing wxWidgets. + +[3]: https://www.wxwidgets.org/blog/2019/01/wxwidgets-and-vcpkg/ +[4]: https://github.com/microsoft/vcpkg + + +Building from Source +-------------------- + +### Getting the sources + +To build the library you need to get its sources first. The recommended way to +do it is to use Git to check them out from the official wxWidgets repository +using the following command: + + $ git clone --recurse-submodules https://github.com/wxWidgets/wxWidgets.git + +Alternatively, you can download the sources from the [downloads page][1]. +Please note that all the source archives in different formats (ZIP, 7z, +tar.bz2) contain the same files, but use different line ending formats: Unix +("LF") for the latter one and DOS ("CR LF") for the two other ones, and it is +usually preferable to choose the format corresponding to the current platform. +When downloading the sources with DOS ends of lines, prefer 7z format for much +smaller file size. + + +### Selecting the build system + +wxWidgets can be built using [CMake](https://cmake.org/) under all platforms. +Please follow [CMake build instructions](@ref overview_cmake) if you prefer to +use it. + +Otherwise, please use the appropriate instructions depending on your platform: + +- For native wxMSW port under [Microsoft Windows](@ref plat_msw_install). +- For wxGTK under [Linux and other Unix-like systems](@ref plat_gtk_install). +- For native wxOSX port under [macOS](@ref plat_osx_install). + +The wxWidgets ports mentioned above are the main ones, however other variants +also exist, see [platform details](@ref page_port) page for the full list. From 8f0045b3a6602bf4012977bacb97d4a78b212678 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sun, 11 Apr 2021 14:30:01 +0200 Subject: [PATCH 5/5] Add "Verifying the Installation" section Briefly explain how to check that wxWidgets is installed correctly. This is again redundant with the information already present elsewhere, but it seems worth repeating it here. --- docs/doxygen/overviews/install.md | 36 +++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/docs/doxygen/overviews/install.md b/docs/doxygen/overviews/install.md index ab47e4e99e..6b7975831c 100644 --- a/docs/doxygen/overviews/install.md +++ b/docs/doxygen/overviews/install.md @@ -79,3 +79,39 @@ Otherwise, please use the appropriate instructions depending on your platform: The wxWidgets ports mentioned above are the main ones, however other variants also exist, see [platform details](@ref page_port) page for the full list. + + +Verifying the Installation +-------------------------- + +After installing wxWidgets, it is recommended to check that the library can +actually be used by building a minimal wxWidgets program using it, such as +`samples/minimal/minimal.cpp` included in wxWidgets distributions. + +You may choose to build this program in any of the following ways: + +- Directly from command line under any Unix-like systems, including macOS and + Unix-like environments such as Cygwin or MSYS2 under MSW, just run + + $ c++ -o minimal minimal.cpp `wx-config --cxxflags --libs` + + Please note that you *must* use `wx-config` to obtain the compiler and linker + flags in this case. + +- Using CMake, and the provided `samples/minimal/CMakeLists.txt` file. + +- Using Microsoft Visual Studio IDE: simply create a new project and add the + provided `wxwidgets.props` property sheet file to it as explained in the + [instructions](@ref #msw_build_apps) and build the project as usual. + +- Using another IDE with wxWidgets support, such as [Code::Blocks][1] or + [CodeLite][2], please use the IDE wizards. + +[1]: https://www.codeblocks.org/ +[2]: https://codelite.org/ + +- If you use another IDE, under Unix you should run `wx-config --cxxflags` and + `wx-config --libs` commands separately and copy-and-paste their output to the + "Additional preprocessor options" and "Additional linker options" fields in + your IDE, respectively. Under MSW systems you need to configure the IDE using + the instructions in the ["manual setup"](@ref #msw_build_apps) section.