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.