From 1b5e3649e51ca84e0ac7eb71a6bf86217197172e Mon Sep 17 00:00:00 2001 From: Tobias Taschner Date: Wed, 3 Oct 2018 18:11:54 +0200 Subject: [PATCH] Integrate MSW, OS X and iOS build instructions into doxygen Make build instructions available in doxygen but keep the old folder structure. --- docs/doxygen/Doxyfile | 5 +- docs/doxygen/mainpages/platdetails.h | 7 +- docs/ios/install.md | 27 ++++ docs/ios/readme.txt | 29 ---- docs/msw/{gtk.txt => gtk.md} | 10 +- docs/msw/{install.txt => install.md} | 198 +++++++++++++++------------ docs/msw/msys2-gtk.md | 124 +++++++++++++++++ docs/msw/msys2-gtk.txt | 111 --------------- docs/msw/msys2-msw.md | 101 ++++++++++++++ docs/msw/msys2-msw.txt | 92 ------------- docs/msw/readme.txt | 2 +- docs/msw/{winxp.txt => winxp.md} | 48 ++++--- docs/osx/{install.txt => install.md} | 73 +++++----- docs/osx/readme.txt | 4 +- 14 files changed, 438 insertions(+), 393 deletions(-) create mode 100644 docs/ios/install.md rename docs/msw/{gtk.txt => gtk.md} (91%) rename docs/msw/{install.txt => install.md} (84%) create mode 100644 docs/msw/msys2-gtk.md delete mode 100644 docs/msw/msys2-gtk.txt create mode 100644 docs/msw/msys2-msw.md delete mode 100644 docs/msw/msys2-msw.txt rename docs/msw/{winxp.txt => winxp.md} (66%) rename docs/osx/{install.txt => install.md} (70%) diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index bef0fc9a9d..717e859b79 100644 --- a/docs/doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -100,7 +100,7 @@ ALIASES += appearance_brief{2}="\htmlonly
\endhtmlonly\n\1\htmlonly\endhtmlonly\n\image html generic/\2.png\n\htmlonly
\endhtmlonly" # aliases for the creation of "named member groups" -# USAGE: the first argument must not contain spaces and be a unique identifier +# USAGE: the first argument must not contain spaces and be a unique identifier # of the member group for the class being documented; # the second argument is the member group name and can contain spaces # See wxString as an usage example. @@ -292,6 +292,9 @@ WARN_LOGFILE = doxygen.log INPUT = mainpages \ groups \ overviews \ + ../ios \ + ../msw \ + ../osx \ ../../interface INPUT_ENCODING = UTF-8 FILE_PATTERNS = *.h *.md diff --git a/docs/doxygen/mainpages/platdetails.h b/docs/doxygen/mainpages/platdetails.h index f4beee8625..ec95b1e25c 100644 --- a/docs/doxygen/mainpages/platdetails.h +++ b/docs/doxygen/mainpages/platdetails.h @@ -62,8 +62,7 @@ distribution. wxOSX/Cocoa is the port of wxWidgets for the OS X platform. It requires OS X 10.7 or later and fully supports 64 bit builds. -For further information, please see the files in @c docs/osx in the -distribution. +@subpage plat_osx_install "Build and Install Instructions" @@ -105,7 +104,7 @@ This port can be compiled with several compilers including Microsoft Studio VC++ 2003 or later, Borland 5.5, MinGW32, Cygwin as well as cross-compilation with a Linux-hosted MinGW32 tool chain. -For further information, please see the files in docs/msw in the distribution. +@subpage plat_msw_install "Build and Install Instructions" @subsection page_port_wxmsw_resources Resources and Application Icon @@ -175,7 +174,7 @@ wxiOS is a port of wxWidgets using Cocoa touch libraries for iOS. It is very basic in it current form, but is included for further improvements and very simple applications. It requires iOS 9 or later and fully supports 64 bit builds. -For further information, please see the files in docs/ios in the distribution. +@subpage plat_ios_install "Build Instructions" @section page_port_nativedocs Native Toolkit Documentation diff --git a/docs/ios/install.md b/docs/ios/install.md new file mode 100644 index 0000000000..9892c59e4d --- /dev/null +++ b/docs/ios/install.md @@ -0,0 +1,27 @@ +Building wxWidgets for iOS {#plat_ios_install} +---------------------------- + +wxiOS is far from a full supported port, but can be used +as base for simple applications and future improvements. + +It requires Xcode with iOS SDK 9.0 or later. Xcode is available +for free in the OS X app store. + +To build wxiOS you should use Xcode to open the minimal samples +Xcode project file located at: + + samples/minimal/minimal_iphone.xcodeproj + +That project files includes wxiphone.xcodeproj so you just need +to hit run in order to see the minimal sample running in the +simulator. + +The library can also be build via configure/make: + + mkdir build_ios + cd build_ios + ../configure --with-osx_iphone --enable-monolithic \ + --with-macosx-version-min=8.0 --disable-shared \ + --enable-macosx_arch=i386 \ + --with-macosx-sdk=$(xcrun --sdk iphonesimulator --show-sdk-path) + make diff --git a/docs/ios/readme.txt b/docs/ios/readme.txt index 573db30676..928ef715ef 100644 --- a/docs/ios/readme.txt +++ b/docs/ios/readme.txt @@ -4,35 +4,6 @@ wxiOS is far from a full supported port, but can be used as base for simple applications and future improvements. -It requires Xcode with iOS SDK 9.0 or later. Xcode is available -for free in the OS X app store. - -More info about the wxWidgets project (including all the -other ports and version of wxWidgets) can be found at the -main wxWidgets homepage at: - - https://www.wxwidgets.org/ - -To build wxiOS you should use Xcode to open the minimal samples -Xcode project file located at: - - samples/minimal/minimal_iphone.xcodeproj - -That project files includes wxiphone.xcodeproj so you just need -to hit run in order to see the minimal sample running in the -simulator. - -The library can also be build via configure/make: - - mkdir build_ios - cd build_ios - ../configure --with-osx_iphone --enable-monolithic \ - --with-macosx-version-min=8.0 --disable-shared \ - --enable-macosx_arch=i386 \ - --with-macosx-sdk=$(xcrun --sdk iphonesimulator --show-sdk-path) - make - - Please send problems concerning installation, feature requests, bug reports or comments to the wxWidgets users list. These can be found at https://www.wxwidgets.org/support/mailing-lists/ diff --git a/docs/msw/gtk.txt b/docs/msw/gtk.md similarity index 91% rename from docs/msw/gtk.txt rename to docs/msw/gtk.md index 6756ea61ec..631884bb18 100644 --- a/docs/msw/gtk.txt +++ b/docs/msw/gtk.md @@ -1,4 +1,4 @@ -Building wxGTK port with Win32 GDK backend +Building wxGTK port with Win32 GDK backend {#plat_msw_gtk} ------------------------------------------ GTK+ widget toolkit has multiple GDK backends and one of them is Win32. @@ -11,14 +11,15 @@ These notes don't consider building wxGTK with X11 backend under Windows. Building steps: 1. wxGTK/Win32 build is similar to wxMSW one and you should have configured -and be able to build wxWidgets as described in docs/msw/install.txt +and be able to build wxWidgets as described in @ref plat_msw_install 2. wxGTK/Win32 is disabled by default in wxWidgets, you need to enable it in bakefiles manually. Apply following patch manually or using Cygwin: - patch -p0 < docs/msw/gtkfix.patch + patch -p0 < docs/msw/gtkfix.patch Regenerate required make/project files: + cd build\bakefiles bakefile_gen @@ -31,6 +32,7 @@ in the C:\gtk directory. 4. Building 4.1 If you are using Visual C++ project files you need to setup GTK+ 2 include directories + C:\gtk\lib\include\gtk-2.0 C:\gtk\lib\include\glib-2.0 C:\gtk\lib\include\cairo @@ -44,7 +46,7 @@ and library directory C:\gtk\lib\ - See http://msdn.microsoft.com/en-us/library/t9az1d21(v=vs.90).aspx +See http://msdn.microsoft.com/en-us/library/t9az1d21(v=vs.90).aspx Open solution file in build\msw directory, select "GTK+ Debug" solution configuration and build the solution. To be sure that everything is as expected diff --git a/docs/msw/install.txt b/docs/msw/install.md similarity index 84% rename from docs/msw/install.txt rename to docs/msw/install.md index d3a69b8302..6e6e5f1146 100644 --- a/docs/msw/install.txt +++ b/docs/msw/install.md @@ -1,37 +1,28 @@ - Installing wxWidgets for Windows - -------------------------------- +Installing wxWidgets for Windows {#plat_msw_install} +-------------------------------- This is wxWidgets for Microsoft Windows (XP, Vista, 7, 8, 10, etc) including both 32 bit and 64 bit versions. +[TOC] -Table of Contents: - - Installation - - Building wxWidgets - - Configuring the Build - - Building Applications Using wxWidgets - - -Installation +Installation {#msw_install} ============ If you are using one of the supported compilers, you can download the pre-built in binaries from - https://github.com/wxWidgets/wxWidgets/releases/v3.1.1 +https://github.com/wxWidgets/wxWidgets/releases/v3.1.1 In this case, just uncompress the binaries archive under any directory -and skip to "Building Applications Using wxWidgets" part. +and skip to [Building Applications Using wxWidgets](#msw_build_apps) part. Otherwise, or if you want to build a configuration of the library different from the default one, you need to build the library from sources before using it. -If you use CMake, please see - - https://docs.wxwidgets.org/trunk/overview_cmake.html - -for building wxWidgets using it. +If you use CMake, please see @ref overview_cmake for +building wxWidgets using it. The first step, which you may have already performed, unless you are reading this file online, is to download the source archive and @@ -46,22 +37,22 @@ actually required, this makes using the library more convenient and this environment variable is used in the examples below. NB: If you checked your sources from version control repository and - didn't obtain them from a release file, you also need to copy - include/wx/msw/setup0.h to include/wx/msw/setup.h and to remember - to update the latter whenever the former changes, otherwise you - will get compilation errors if any new symbols are added to - setup0.h file in the repository. +didn't obtain them from a release file, you also need to copy +`include/wx/msw/setup0.h` to `include/wx/msw/setup.h` and to remember +to update the latter whenever the former changes, otherwise you +will get compilation errors if any new symbols are added to +setup0.h file in the repository. - If you have no intention of modifying setup.h, you may avoid this - problem by creating a symbolic link to setup0.h instead of making - a copy of it using mklink, from an admin command prompt: +If you have no intention of modifying setup.h, you may avoid this +problem by creating a symbolic link to setup0.h instead of making +a copy of it using mklink, from an admin command prompt: - cd %WXWIN%\include\wx\msw\ - mklink setup.h setup0.h + cd %WXWIN%\include\wx\msw\ + mklink setup.h setup0.h -Building wxWidgets +Building wxWidgets {#msw_build} ================== The following sections explain how to compile wxWidgets with each supported @@ -70,7 +61,7 @@ building your application using wxWidgets. All makefiles and project are located in build\msw directory. -Microsoft Visual C++ Compilation +Microsoft Visual C++ Compilation {#msw_build_msvs} ---------------------------------------------------------------- * From command line using the provided makefiles: @@ -79,7 +70,7 @@ Microsoft Visual C++ Compilation must have been installed to the "Start" menu or the "Start" screen by MSVS installation. -1. Change directory to %WXWIN%\build\msw and type +1. Change directory to \%WXWIN\%\build\msw and type > nmake /f makefile.vc @@ -99,7 +90,7 @@ Microsoft Visual C++ Compilation See "Configuring the Build" for more information about the additional parameters that can be specified on the command line. -2. To verify your build, change the directory to %WXWIN%\samples\minimal and +2. To verify your build, change the directory to \%WXWIN\%\samples\minimal and run the same nmake command (with the same parameters there), this should create a working minimal wxWidgets sample. @@ -120,7 +111,7 @@ are not always built in the correct order, and this may result in link errors. Simply do the build again, up to 3 times, to fix this. -Special notes for Visual Studio 2010+: +### Special notes for Visual Studio 2010+ For Visual Studio 2010+ solutions it is possible to customize the build by creating a wx_local.props file in the build\msw directory which is used, if it @@ -132,8 +123,8 @@ make the file is to copy wx_setup.props to wx_local.props and then edit local. For example, if you are building wxWidgets libraries using multiple versions of Visual Studio you could change wxCompilerPrefix to include the toolset: -- vc -+ vc$(PlatformToolsetVersion) + - vc + + vc$(PlatformToolsetVersion) Following that example if you are using Visual Studio 2013 and open wx_vc12.sln it will build using the "vc120" prefix for the build directories @@ -147,28 +138,31 @@ updated with it. For example the version information in wx_setup.props could change and the information in your wx_local.props would be outdated. It is your responsibility to monitor for such situations. -Improve debugging for Visual Studio 2012+: +### Improve debugging for Visual Studio 2012+ Debug visualizers for Visual Studio 2012+ are provided which makes inspecting various wxWidgets classes easier to view while debugging. To use them: -1. Open the folder %WXWIN%\misc\msvc -2. Open the folder %USERPROFILE%\My Documents\Visual Studio 2012\Visualizers\ +1. Open the folder \%WXWIN\%\misc\msvc +2. Open the folder \%USERPROFILE\%\My Documents\Visual Studio 2012\Visualizers\ (or the corresponding location for newer versions, e.g. ...2013\Visualizers) 3. Copy wxWidgets.natvis and autoexp.inc 4. For Visual Studio 2013+ additionally copy wxWidgets.2013.natvis -Cygwin/MinGW Compilation +Cygwin/MinGW Compilation {#msw_build_cygwin} ---------------------------------------------------------------- wxWidgets supports Cygwin, MinGW, MinGW-w64 and TDM-GCC tool chains under Windows. They can be downloaded from: - http://www.cygwin.com/ - http://www.mingw.org/ - http://mingw-w64.sourceforge.net/ - http://tdm-gcc.tdragon.net/ +http://www.cygwin.com/ + +http://www.mingw.org/ + +http://mingw-w64.sourceforge.net/ + +http://tdm-gcc.tdragon.net/ respectively. Please retrieve and install the latest version of your preferred tool chain by following the instructions provided by these packages. Notice @@ -189,7 +183,7 @@ All of these tool chains can be used either with Unix-like configure+make build process (preferred) or with the provided makefile.gcc makefiles without using configure: -* Using configure +### Using configure This method works in exactly the same way as under Unix systems, including OS X, and requires a Unix-like environment to work, i.e. @@ -231,7 +225,7 @@ either MSYS or Cygwin. so this step can usually be omitted. -* Using plain makefiles: +### Using plain makefiles: NOTE: The makefile.gcc makefiles are for compilation under MinGW using Windows command interpreter (command.com/cmd.exe), they won't work @@ -240,7 +234,7 @@ NOTE: The makefile.gcc makefiles are for compilation under MinGW using 0. Open DOS command line window (cmd.exe, *not* Bash sh.exe). -1. Change directory to %WXWIN%\build\msw and type +1. Change directory to \%WXWIN\%\build\msw and type > mingw32-make -f makefile.gcc @@ -263,7 +257,7 @@ NOTE: The makefile.gcc makefiles are for compilation under MinGW using -Borland C++ Compilation +Borland C++ Compilation {#msw_build_borland} ---------------------------------------------------------------- WARNING: Borland instructions are out of date, please send us your @@ -278,7 +272,7 @@ debugger is very good. To avoid linker errors you will need to add -DSHARED=1 to the makefile line for the library The version 5.6 included in Borland C++ Builder 2006 works as well after the -following small change: please remove the test for __WINDOWS__ from line 88 +following small change: please remove the test for `__WINDOWS__` from line 88 of the file BCCDIR\include\stl\_threads.h. Compiling using the makefiles: @@ -302,7 +296,7 @@ debug mode, edit makefile.bcc and change /aa to /Tpe in link commands. Using the Debugger and IDE in BDS or Turbo Explorer --------------------------------------------------- -Doubleclick / open %WXWIN%\samples\minimal\borland.bdsproj. The current version +Doubleclick / open \%WXWIN\%\samples\minimal\borland.bdsproj. The current version is to be used with a dynamic build of wxWidgets-made by running make -f Makefile.bcc -DBUILD=debug -DSHARED=1 in wxWidgets\build\msw. You also need the wxWidgets\lib\bcc_dll @@ -324,16 +318,16 @@ Compiling using the IDE files for Borland C++ 5.0 and using CBuilder IDE In all of your wxWidgets applications, your source code should include the following preprocessor directive: -#ifdef __BORLANDC__ -#pragma hdrstop -#endif + #ifdef __BORLANDC__ + #pragma hdrstop + #endif (check the samples -- e.g., \wx2\samples\minimal\minimal.cpp -- for more details) -Configuring the Build +Configuring the Build {#msw_build_config} ================================================================ NOTE: If you use configure to build the library with Cygwin/MinGW, the @@ -344,7 +338,7 @@ Library configuration ---------------------------------------------------------------- While it is never necessary to do it, you may want to change some of -the options in the %WXWIN%\include\wx\msw\setup.h file before building +the options in the \%WXWIN\%\\include\\wx\\msw\\setup.h file before building wxWidgets. This file is heavily commented, please read it and enable or disable the features you would like to compile wxWidgets with[out]. @@ -381,17 +375,20 @@ depending on the compiler used. The full list of the build settings follows: -BUILD=release +* BUILD=release + Builds release version of the library. It differs from default 'debug' in lack of appended 'd' in name of library and uses the release CRT libraries instead of debug ones. Notice that even release builds do include debug information by default, see DEBUG_FLAG for more information about it. -SHARED=1 +* SHARED=1 + Build shared libraries (DLLs). By default, DLLs are not built (SHARED=0). -UNICODE=0 +* UNICODE=0 + To completely disable Unicode support (default is UNICODE=1). It should not be necessary to do this. @@ -399,54 +396,62 @@ UNICODE=0 Unicode build) and the directory where the library and setup.h are stored (ditto). -WXUNIV=1 +* WXUNIV=1 + Build wxUniversal instead of native wxMSW -MONOLITHIC=1 +* MONOLITHIC=1 + Starting with version 2.5.1, wxWidgets has the ability to be built as several smaller libraries instead of single big one as used to be the case in 2.4 and older versions. This is called "multilib build" and is the default behaviour of makefiles. You can still build single library ("monolithic build") by setting MONOLITHIC variable to 1. -USE_GUI=0 +* USE_GUI=0 + Disable building GUI parts of the library, build only wxBase components used by console applications. Note that if you leave USE_GUI=1 then both wxBase and GUI libraries are built. -USE_$(LIBRARY)=0 +* USE_$(LIBRARY)=0 + Do not build the corresponding library (all libraries are built by default). Library which can be disabled in this way are: AUI, HTML, MEDIA, GL (the option name is USE_OPENGL for this one), PROPGRID, QA, RIBBON, RICHTEXT, STC, WEBVIEW, XRC. -RUNTIME_LIBS=static +* RUNTIME_LIBS=static + Links static version of C and C++ runtime libraries into the executable, so that the program does not depend on DLLs provided with the compiler (e.g. Visual C++'s msvcrt.dll or Borland's cc3250mt.dll). Caution: Do not use static runtime libraries when building DLL (SHARED=1)! -DEBUG_FLAG=0 -DEBUG_FLAG=1 -DEBUG_FLAG=2 +* DEBUG_FLAG=0 +* DEBUG_FLAG=1 +* DEBUG_FLAG=2 + Specifies the level of debug support in wxWidgets. Notice that this is independent from both BUILD and DEBUG_INFO options. By default always set to 1 meaning that debug support is enabled: asserts are compiled into the code (they are inactive by default in release builds of the application but can be enabled), wxLogDebug() and wxLogTrace() are available - and __WXDEBUG__ is defined. Setting it to 0 completely disables all + and `__WXDEBUG__` is defined. Setting it to 0 completely disables all debugging code in wxWidgets while setting it to 2 enables even the time consuming assertions and checks which are deemed to be unsuitable for production environment. -DEBUG_INFO=0 -DEBUG_INFO=1 +* DEBUG_INFO=0 +* DEBUG_INFO=1 + This option affects whether debugging information is generated. If omitted or set to 'default' its value is determined the value of the BUILD option. -DEBUG_RUNTIME_LIBS=0 -DEBUG_RUNTIME_LIBS=1 +* DEBUG_RUNTIME_LIBS=0 +* DEBUG_RUNTIME_LIBS=1 + (VC++ only.) If set to 1, msvcrtd.dll is used, if to 0, msvcrt.dll is used. By default msvcrtd.dll is used only if the executable contains debug info and msvcrt.dll if it doesn't. It is sometimes @@ -455,11 +460,13 @@ DEBUG_RUNTIME_LIBS=1 usable .pdb files with debug information) and this setting makes it possible. -TARGET_CPU=X64|ARM64|IA64 +* TARGET_CPU=X64|ARM64|IA64 + (VC++ only.) Set this variable to build for x86_64 systems. If unset, x86 build is performed. -VENDOR= +* VENDOR=\ + Set this to a short string identifying your company if you are planning to distribute wxWidgets DLLs with your application. Default value is 'custom'. This string is included as part of DLL name. wxWidgets DLLs contain compiler @@ -468,72 +475,74 @@ VENDOR= default settings. If you set VENDOR=mycorp, the name will change to wxmsw311u_core_vc_mycorp.dll. -CFG= +* CFG=\ + Sets configuration name so that you can have multiple wxWidgets builds with different setup.h settings coexisting in same tree. The value of this option is appended to the build directories names. This is useful for building the library in some non-default configuration, - e.g. you could change wxUSE_STL to 1 in %WXWIN%\include\wx\msw\setup.h and + e.g. you could change wxUSE_STL to 1 in \%WXWIN\%\include\wx\msw\setup.h and then build with "CFG=-stl". Alternatively, you could build with e.g. "RUNTIME_LIBS=static CFG=-mt" when using MSVC. -COMPILER_PREFIX= +* COMPILER_PREFIX=\ + If you build with multiple versions of the same compiler, you can put their outputs into directories like "vc6_lib", "vc8_lib" etc. instead of "vc_lib" by setting this variable to e.g. "vc6". This is merely a convenience variable, you can achieve the same effect (but different directory names) with the CFG option. -CFLAGS -CXXFLAGS -CPPFLAGS -LDFLAGS +* CFLAGS +* CXXFLAGS +* CPPFLAGS +* LDFLAGS + Additional flags to be used with C compiler, C++ compiler, C preprocessor (used for both C and C++ compilation) and linker, respectively. -Building Applications Using wxWidgets +Building Applications Using wxWidgets {#msw_build_apps} ===================================== If you want to use CMake for building your project, please see - - https://docs.wxwidgets.org/trunk/overview_cmake.html#cmake_apps +@ref overview_cmake. Otherwise follow the instructions below for "manual" setup of your project. We suppose that wxWidgets sources are under the directory $WXWIN (notice that different tool chains refer to environment variables such as WXWIN in different ways, e.g. MSVC users should use $(WXWIN) instead of just -$WXWIN). And we will use as a shortcut for the subdirectory of +$WXWIN). And we will use \ as a shortcut for the subdirectory of $WXWIN\lib which is composed from several parts separated by underscore: first, a compiler-specific prefix (e.g. "vc" for MSVC, "gcc" for g++ or the value of COMPILER_PREFIX if you set it explicitly), then optional "x64" if building in 64 bits and finally either "lib" or "dll" depending on whether static or dynamic wx libraries are being used. -For example, WXWIN could be "c:\wxWidgets\3.4.5" and could be +For example, WXWIN could be "c:\wxWidgets\3.4.5" and \ could be "c:\wxWidgets\3.4.5\lib\vc_x64_lib" for 64-bit static libraries built with MSVC. Here is what you need to do: -* Add $WXWIN\include to the +* Add $WXWIN\\include to the - compiler - resource compiler include paths. * If using MSVC, prepend $WXWIN\include\msvc to the include paths too. - Otherwise, append \mswu[d] to the include paths, where "d" should + Otherwise, append \\mswu[d] to the include paths, where "d" should be used for debug builds only. * Define the following symbols for the preprocessor: - - __WXMSW__ to ensure you use the correct wxWidgets port. + - `__WXMSW__` to ensure you use the correct wxWidgets port. - _UNICODE unless you want to use deprecated ANSI build of wxWidgets. - NDEBUG if you want to build in release mode, i.e. disable asserts. - WXUSINGDLL if you are using DLL build of wxWidgets. * If using MSVC 7 only (i.e. not for later versions), also define wxUSE_RC_MANIFEST=1 and WX_CPU_X86. -* Add directory described above to the libraries path. +* Add \ directory described above to the libraries path. When using MSVC, the libraries are linked automatically using "#pragma comment(lib)" feature of this compiler. With all the other compilers you also @@ -554,3 +563,18 @@ using wxWidgets and always work, so in case of a problem, e.g. if the instructions here are out of date, you can always simply copy a makefile or project file from $WXWIN\samples\minimal or some other sample and adapt it to your application. + +If you are not using Visual Studio 2010 or newer please see +@subpage plat_msw_winxp "Windows XP Support" to enable visual styles in your +application. + +Advanced Library Configurations {#msw_advanced} +=============================== +Build instructions to less common library configuartions using different UI +backends are avaiable here. + +@subpage plat_msw_msys2 "Building with Win32 MSys2 backend" + +@subpage plat_msw_msys2_gtk "Building with Win32 MSys2 GDK backend" + +@subpage plat_msw_gtk "Building wxGTK port with Win32 GDK backend" diff --git a/docs/msw/msys2-gtk.md b/docs/msw/msys2-gtk.md new file mode 100644 index 0000000000..e6cb03567a --- /dev/null +++ b/docs/msw/msys2-gtk.md @@ -0,0 +1,124 @@ +Building wxGTK port with Win32 MSys2 GDK backend {#plat_msw_msys2_gtk} +------------------------------------------------ + +GTK+ widget toolkit has multiple GDK backends and one of them is Win32. +It is a wrapper around Windows API. + +These notes don't consider building wxGTK with X11 backend under Windows. + +The MSys2 website is http://www.msys2.org/ + +These building steps are NOT the normal way to build MSys2 MinGW packages. +But, they are a way the wxWidgets developers can test that wxWidgets +can build the wxGTK/Win32 libraries under MSys2 MinGW. + +For the MSys2 way please see + https://github.com/Alexpux/MINGW-packages and + https://github.com/msys2/msys2/wiki/Creating-packages + +Building steps: + +**Warning**: At the time these directions were written the GTK version 3 + was NOT able to create wxGTK/Win32 libraries that were usable. + +1. Install the mingw32 packages needed to build wxGTK/Win32 using the + configure/make build method. + From the MSys2 prompt or MSys2 MinGW prompt: + + The 32 bit Mingw packages are prefixed with "mingw-w64-i686-"; + Change the prefix to "mingw-w64-x86_64-" if you wish to do 64 bit. + + pacman -S --needed --noconfirm make + pacman -S --needed --noconfirm mingw-w64-i686-libjpeg-turbo + pacman -S --needed --noconfirm mingw-w64-i686-libpng + pacman -S --needed --noconfirm mingw-w64-i686-libtiff + pacman -S --needed --noconfirm mingw-w64-i686-gcc + pacman -S --needed --noconfirm mingw-w64-i686-pkg-config + ## gtk2 can take a long time to update/find fonts + pacman -S --needed --noconfirm mingw-w64-i686-gtk2 + + + Packages that are needed but are normally installed already. + + pacman -S --needed --noconfirm mingw-w64-i686-gcc-libs + pacman -S --needed --noconfirm mingw-w64-i686-expat + pacman -S --needed --noconfirm mingw-w64-i686-xz + pacman -S --needed --noconfirm mingw-w64-i686-zlib + pacman -S --needed --noconfirm mingw-w64-i686-gdk-pixbuf2 + + +2. Build the wxGTK/Win32 static library + 1. Open MSys2 MinGW Prompt + (These steps were tested on MinGW32; but, should work under MinGW64) + 2. Use the cd command to change directory to the wxWidgets top folder. + + 3. Create the "build-gtk2-static" folder to build the static libraries + + mkdir -p build-gtk2-static + + 4. Configure wxWidgets + Option "--disable-precomp-headers" is NOT needed. + It is being used to test for compile issues. + + Remove configure option "--disable-wxdib" to set wxUSE_WXDIB to 1. + The directions docs/msw/gtk.txt results in wxUSE_WXDIB set to 1. + + cd build-gtk2-static && \ + ../configure --with-gtk=2 \ + --disable-wxdib \ + --disable-shared \ + --disable-precomp-headers \ + && cd .. + + 5. clean the wxGTK static libraries + + cd build-gtk2-static && make clean && cd .. + + 6. make the wxGTK static libraries + + cd build-gtk2-static && make && cd .. + + +3. Build and run the minimal static sample + 1. Clean the minimal sample + + cd build-gtk2-static/samples/minimal && make clean && cd ../../.. + + 2. Build the minimal sample + + cd build-gtk2-static/samples/minimal && make && cd ../../.. + + 3. Run the minimal sample + + ./build-gtk2-static/samples/minimal/minimal.exe + + +4. Build most of the static samples + 1. Clean most of the static samples + + cd build-gtk2-static/samples && make clean && cd ../.. + + 2. Build most of the static samples + + cd build-gtk2-static/samples && make && cd ../.. + + +5. Run the drawing static sample + + cd samples/drawing && ../../build-gtk2-static/samples/drawing/drawing.exe && cd ../.. + +6. Run the splash static sample + + cd samples/splash && ../../build-gtk2-static/samples/splash/splash.exe && cd ../.. + +7. Run the widgets static sample + + cd samples/widgets && ../../build-gtk2-static/samples/widgets/widgets.exe && cd ../.. + +8. Run the toolbar static sample + + cd samples/toolbar && ../../build-gtk2-static/samples/toolbar/toolbar.exe && cd ../.. + +9. Run the image static sample + + cd samples/image && ../../build-gtk2-static/samples/image/image.exe && cd ../.. diff --git a/docs/msw/msys2-gtk.txt b/docs/msw/msys2-gtk.txt deleted file mode 100644 index bc7a08a9a5..0000000000 --- a/docs/msw/msys2-gtk.txt +++ /dev/null @@ -1,111 +0,0 @@ -Building wxGTK port with Win32 MSys2 GDK backend ------------------------------------------------- - -GTK+ widget toolkit has multiple GDK backends and one of them is Win32. -It is a wrapper around Windows API. - -These notes don't consider building wxGTK with X11 backend under Windows. - -The MSys2 website is http://www.msys2.org/ - -These building steps are NOT the normal way to build MSys2 MinGW packages. -But, they are a way the wxWidgets developers can test that wxWidgets -can build the wxGTK/Win32 libraries under MSys2 MinGW. - -For the MSys2 way please see - https://github.com/Alexpux/MINGW-packages and - https://github.com/msys2/msys2/wiki/Creating-packages - -Building steps: - -#Note: The "#" is used in front of a comment to help the people who cut -# and paste these directions. -#Warning: At the time these directions were written the GTK version 3 -# was NOT able to create wxGTK/Win32 libraries that were usable. - -#1. Install the mingw32 packages needed to build wxGTK/Win32 using the -# configure/make build method. -# From the MSys2 prompt or MSys2 MinGW prompt: - -# The 32 bit Mingw packages are prefixed with "mingw-w64-i686-"; -# Change the prefix to "mingw-w64-x86_64-" if you wish to do 64 bit. - -pacman -S --needed --noconfirm make -pacman -S --needed --noconfirm mingw-w64-i686-libjpeg-turbo -pacman -S --needed --noconfirm mingw-w64-i686-libpng -pacman -S --needed --noconfirm mingw-w64-i686-libtiff -pacman -S --needed --noconfirm mingw-w64-i686-gcc -pacman -S --needed --noconfirm mingw-w64-i686-pkg-config -## gtk2 can take a long time to update/find fonts -pacman -S --needed --noconfirm mingw-w64-i686-gtk2 - - -# Packages that are needed but are normally installed already. -pacman -S --needed --noconfirm mingw-w64-i686-gcc-libs -pacman -S --needed --noconfirm mingw-w64-i686-expat -pacman -S --needed --noconfirm mingw-w64-i686-xz -pacman -S --needed --noconfirm mingw-w64-i686-zlib -pacman -S --needed --noconfirm mingw-w64-i686-gdk-pixbuf2 - - -#2. Build the wxGTK/Win32 static library -#2a.Open MSys2 MinGW Prompt -# (These steps were tested on MinGW32; but, should work under MinGW64) -#2b.Use the cd command to change directory to the wxWidgets top folder. - - -#2c.Create the "build-gtk2-static" folder to build the static libraries -mkdir -p build-gtk2-static - -#2d.Configure wxWidgets -# Option "--disable-precomp-headers" is NOT needed. -# It is being used to test for compile issues. -# -# Remove configure option "--disable-wxdib" to set wxUSE_WXDIB to 1. -# The directions docs/msw/gtk.txt results in wxUSE_WXDIB set to 1. -cd build-gtk2-static && \ - ../configure --with-gtk=2 \ - --disable-wxdib \ - --disable-shared \ - --disable-precomp-headers \ - && cd .. - -#2e.clean the wxGTK static libraries -cd build-gtk2-static && make clean && cd .. - -#2f.make the wxGTK static libraries -cd build-gtk2-static && make && cd .. - - -#3 Build and run the minimal static sample -#3a.Clean the minimal sample -cd build-gtk2-static/samples/minimal && make clean && cd ../../.. - -#3b.Build the minimal sample -cd build-gtk2-static/samples/minimal && make && cd ../../.. - -#3c.Run the minimal sample -./build-gtk2-static/samples/minimal/minimal.exe - - -#4 Build most of the static samples -#4a.Clean most of the static samples -cd build-gtk2-static/samples && make clean && cd ../.. -#4b.Build most of the static samples -cd build-gtk2-static/samples && make && cd ../.. - - -#5 Run the drawing static sample -cd samples/drawing && ../../build-gtk2-static/samples/drawing/drawing.exe && cd ../.. - -#6 Run the splash static sample -cd samples/splash && ../../build-gtk2-static/samples/splash/splash.exe && cd ../.. - -#7 Run the widgets static sample -cd samples/widgets && ../../build-gtk2-static/samples/widgets/widgets.exe && cd ../.. - -#8 Run the toolbar static sample -cd samples/toolbar && ../../build-gtk2-static/samples/toolbar/toolbar.exe && cd ../.. - -#9 Run the image static sample -cd samples/image && ../../build-gtk2-static/samples/image/image.exe && cd ../.. diff --git a/docs/msw/msys2-msw.md b/docs/msw/msys2-msw.md new file mode 100644 index 0000000000..a0bdedd853 --- /dev/null +++ b/docs/msw/msys2-msw.md @@ -0,0 +1,101 @@ +Building wxMSW port with Win32 MSys2 backend {#plat_msw_msys2} +------------------------------------------------ + +The MSys2 website is http://www.msys2.org/ + +These building steps are NOT the normal way to build MSys2 MinGW packages. +But, they are a way the wxWidgets developers can test that wxWidgets +can build the wxMSW libraries under MSys2 MinGW. + +For the MSys2 way please see https://github.com/Alexpux/MINGW-packages + +Building steps: + +1. Install the mingw32 packages needed to build wxMSW using the + configure/make build method. + From the MSys2 prompt or MSys2 MinGW prompt: + + The 32 bit Mingw packages are prefixed with "mingw-w64-i686-"; + Change the prefix to "mingw-w64-x86_64-" if you wish to do 64 bit. + + pacman -S --needed --noconfirm make + pacman -S --needed --noconfirm mingw-w64-i686-libjpeg-turbo + pacman -S --needed --noconfirm mingw-w64-i686-libpng + pacman -S --needed --noconfirm mingw-w64-i686-libtiff + pacman -S --needed --noconfirm mingw-w64-i686-gcc + + Packages that are needed but are normally installed already. + + pacman -S --needed --noconfirm mingw-w64-i686-gcc-libs + pacman -S --needed --noconfirm mingw-w64-i686-expat + pacman -S --needed --noconfirm mingw-w64-i686-xz + pacman -S --needed --noconfirm mingw-w64-i686-zlib + + +2. Build the wxMSW static library + 1. Open MSys2 MinGW Prompt + (These steps were tested on MinGW32; but, should work under MinGW64) + 2. Use the cd command to change directory to the wxWidgets top folder. + + 3. Create the "build-msw-static" folder to build the static libraries + + mkdir -p build-msw-static + + 4. Configure wxWidgets + + Option "--disable-precomp-headers" is NOT needed. + I am doing it to check for compile issues; + And, I think my old 32 bit Windows machine + works best with it disabled. + + cd build-msw-static && \ + ../configure --with-msw \ + --disable-shared \ + --disable-precomp-headers \ + && cd .. + + 5. make the wxMSW static libraries + + cd build-msw-static && make && cd .. + +3. Build and run the minimal static sample + + 1. Clean the minimal sample + + cd build-msw-static/samples/minimal && make clean && cd ../../.. + + 2. Build the minimal sample + + cd build-msw-static/samples/minimal && make && cd ../../.. + + 3. Run the minimal sample + + ./build-msw-static/samples/minimal/minimal.exe + +4. Clean the static samples + + cd build-msw-static/samples && make clean && cd ../.. + +5. Build and run the typetest static sample to verify MIME database works + + cd build-msw-static/samples/typetest && make && cd ../../.. + ./build-msw-static/samples/typetest/typetest.exe + +6. Build and run the drawing static sample + + cd build-msw-static/samples/drawing && make && cd ../../.. + cd samples/drawing && ../../build-msw-static/samples/drawing/drawing.exe && cd ../.. + +7. Build and run the splash static sample + + cd build-msw-static/samples/splash && make && cd ../../.. + cd samples/splash && ../../build-msw-static/samples/splash/splash.exe && cd ../.. + +8. Build and run the widgets static sample + + cd build-msw-static/samples/widgets && make && cd ../../.. + cd samples/widgets && ../../build-msw-static/samples/widgets/widgets.exe && cd ../.. + +9. Build all the rest of the static samples + + cd build-msw-static/samples && make && cd ../.. diff --git a/docs/msw/msys2-msw.txt b/docs/msw/msys2-msw.txt deleted file mode 100644 index a88366b2aa..0000000000 --- a/docs/msw/msys2-msw.txt +++ /dev/null @@ -1,92 +0,0 @@ -Building wxMSW port with Win32 MSys2 backend ------------------------------------------------- - -The MSys2 website is http://www.msys2.org/ - -These building steps are NOT the normal way to build MSys2 MinGW packages. -But, they are a way the wxWidgets developers can test that wxWidgets -can build the wxMSW libraries under MSys2 MinGW. - -For the MSys2 way please see https://github.com/Alexpux/MINGW-packages - -Building steps: - -#Note: The "#" is used in front of a comment to help the people who cut -# and paste these directions. - -#1. Install the mingw32 packages needed to build wxMSW using the -# configure/make build method. -# From the MSys2 prompt or MSys2 MinGW prompt: - -# The 32 bit Mingw packages are prefixed with "mingw-w64-i686-"; -# Change the prefix to "mingw-w64-x86_64-" if you wish to do 64 bit. - -pacman -S --needed --noconfirm make -pacman -S --needed --noconfirm mingw-w64-i686-libjpeg-turbo -pacman -S --needed --noconfirm mingw-w64-i686-libpng -pacman -S --needed --noconfirm mingw-w64-i686-libtiff -pacman -S --needed --noconfirm mingw-w64-i686-gcc - -# Packages that are needed but are normally installed already. -pacman -S --needed --noconfirm mingw-w64-i686-gcc-libs -pacman -S --needed --noconfirm mingw-w64-i686-expat -pacman -S --needed --noconfirm mingw-w64-i686-xz -pacman -S --needed --noconfirm mingw-w64-i686-zlib - - -#2. Build the wxMSW static library -#2a.Open MSys2 MinGW Prompt -# (These steps were tested on MinGW32; but, should work under MinGW64) -#2b.Use the cd command to change directory to the wxWidgets top folder. - - -#2c.Create the "build-msw-static" folder to build the static libraries -mkdir -p build-msw-static - -#2d.Configure wxWidgets -# Option "--disable-precomp-headers" is NOT needed. -# I am doing it to check for compile issues; -# And, I think my old 32 bit Windows machine -# works best with it disabled. -cd build-msw-static && \ - ../configure --with-msw \ - --disable-shared \ - --disable-precomp-headers \ - && cd .. - -#2e.make the wxMSW static libraries -cd build-msw-static && make && cd .. - - -#3 Build and run the minimal static sample -#3a.Clean the minimal sample -cd build-msw-static/samples/minimal && make clean && cd ../../.. - -#3b.Build the minimal sample -cd build-msw-static/samples/minimal && make && cd ../../.. - -#3c.Run the minimal sample -./build-msw-static/samples/minimal/minimal.exe - - -#4 Clean the static samples -cd build-msw-static/samples && make clean && cd ../.. - -#5 Build and run the typetest static sample to verify MIME database works -cd build-msw-static/samples/typetest && make && cd ../../.. -./build-msw-static/samples/typetest/typetest.exe - -#6 Build and run the drawing static sample -cd build-msw-static/samples/drawing && make && cd ../../.. -cd samples/drawing && ../../build-msw-static/samples/drawing/drawing.exe && cd ../.. - -#7 Build and run the splash static sample -cd build-msw-static/samples/splash && make && cd ../../.. -cd samples/splash && ../../build-msw-static/samples/splash/splash.exe && cd ../.. - -#8 Build and run the widgets static sample -cd build-msw-static/samples/widgets && make && cd ../../.. -cd samples/widgets && ../../build-msw-static/samples/widgets/widgets.exe && cd ../.. - -#9 Build all the rest of the static samples -cd build-msw-static/samples && make && cd ../.. diff --git a/docs/msw/readme.txt b/docs/msw/readme.txt index 75c619c10b..00511b290a 100644 --- a/docs/msw/readme.txt +++ b/docs/msw/readme.txt @@ -1,7 +1,7 @@ This is wxWidgets for Windows (wxMSW) ------------------------------------- -For information on installing wxWidgets, please see install.txt. +For information on installing wxWidgets, please see install.md. For further information, please see docs/html/index.htm and the wxWidgets reference manual. diff --git a/docs/msw/winxp.txt b/docs/msw/winxp.md similarity index 66% rename from docs/msw/winxp.txt rename to docs/msw/winxp.md index 6c03f97760..a690ced463 100644 --- a/docs/msw/winxp.txt +++ b/docs/msw/winxp.md @@ -1,4 +1,4 @@ -Microsoft Windows XP Support from wxWidgets +Microsoft Windows XP Support from wxWidgets {#plat_msw_winxp} ------------------------------------------- Windows XP introduces the themes (called "visual styles" in the Microsoft @@ -30,27 +30,25 @@ for more details. Here is the example manifest which you can put into controls.exe.manifest file to test theme support using the controls sample: ---- cut here --- - - - -Controls: wxWidgets sample application - - - - - - ---- cut here --- + + + + Controls: wxWidgets sample application + + + + + + diff --git a/docs/osx/install.txt b/docs/osx/install.md similarity index 70% rename from docs/osx/install.txt rename to docs/osx/install.md index 57157981ac..9313a6f737 100644 --- a/docs/osx/install.txt +++ b/docs/osx/install.md @@ -1,58 +1,57 @@ -wxWidgets for OS X installation +wxWidgets for OS X installation {#plat_osx_install} ----------------------------------- +[TOC] + wxWidgets can be compiled using Apple's Cocoa library. -Most OS X developers should start by downloading and installing Xcode +Most OS X developers should start by downloading and installing Xcode from the App Store. It is a free IDE from Apple that provides all of the tools you need for working with wxWidgets. -After Xcode is installed, download wxWidgets-{version}.tar.bz2 and then +After Xcode is installed, download wxWidgets-{version}.tar.bz2 and then double-click on it to unpack it to create a wxWidgets directory. -Next use Terminal (under Applications, Utilities, Terminal) to access a command -prompt. Use cd to change directories to your wxWidgets directory and execute +Next use Terminal (under Applications, Utilities, Terminal) to access a command +prompt. Use cd to change directories to your wxWidgets directory and execute the following sets of commands from the wxWidgets directory. ---------- + mkdir build-cocoa-debug + cd build-cocoa-debug + ../configure --enable-debug + make -mkdir build-cocoa-debug -cd build-cocoa-debug -../configure --enable-debug -make -# Build the samples and demos -cd samples; make;cd .. -cd demos; make;cd .. +Build the samples and demos ---------- + cd samples; make;cd .. + cd demos; make;cd .. After the compilation completes, use Finder to run the samples and demos - Go to build-cocoa-debug/samples to experiment with the Cocoa samples. - Go to build-cocoa-debug/demos to experiment with the Cocoa demos. -Double-click on the executables which have an icon showing three small squares. -The source code for the samples is in wxWidgets/samples -The source code for the demos is in wxWidgets/demos - ---------- +* Go to build-cocoa-debug/samples to experiment with the Cocoa samples. +* Go to build-cocoa-debug/demos to experiment with the Cocoa demos. +* Double-click on the executables which have an icon showing three small squares. +* The source code for the samples is in wxWidgets/samples +* The source code for the demos is in wxWidgets/demos More information about building on OS X is available in the wxWiki. Here are two useful links - https://wiki.wxwidgets.org/Guides_%26_Tutorials - https://wiki.wxwidgets.org/Development:_wxMac + * https://wiki.wxwidgets.org/Guides_%26_Tutorials + * https://wiki.wxwidgets.org/Development:_wxMac ---------- -More advanced topics are covered below. +Advanced topics {#osx_advanced} +=============== ---------- +Installing library {#osx_install} +------------------ If you want to install the library into the system directories you'll need to do this as root. The accepted way of running commands as root is to use the built-in sudo mechanism. First of all, you must be using an account marked as a "Computer Administrator". Then -6) sudo make install -7) type + sudo make install + type \ Note that while using this method is okay for development, it is not recommended that you require endusers to install wxWidgets into their @@ -61,13 +60,13 @@ is to configure wxWidgets with --disable-shared. Another way to avoid it is to make a framework for wxWidgets. Making frameworks is beyond the scope of this document. -Note: +**Note:** It is rarely desirable to install non-Apple software into system directories. By configuring the library with --disable-shared and using the full path to wx-config with the --in-place option you can avoid installing the library. -Apple Developer Tools: Xcode +Apple Developer Tools: Xcode {#osx_xcode} ---------------------------- You can use the project in build/osx/wxcocoa.xcodeproj to build the Cocoa @@ -79,10 +78,10 @@ also wxrc tool which doesn't have its own Xcode project. If you need this tool, the simplest possibility is to build it from the command line after installing the libraries using commands like this: -$ cd utils/wxrc -$ g++ -o wxrc wxrc.cpp `wx-config --cxxflags --libs base,xml` + $ cd utils/wxrc + $ g++ -o wxrc wxrc.cpp `wx-config --cxxflags --libs base,xml` -Creating universal binaries +Creating universal binaries {#osx_universal_bin} --------------------------- The Xcode projects for the wxWidgets library and minimal project are set up @@ -108,11 +107,11 @@ binaries together. Assuming building on a PPC system: 2. Then, build for Intel, in a different folder. This time use: -export CFLAGS="-g -isysroot /Developer/SDKs/MacOSX10.7.sdk -arch i386" -export LDFLAGS="-syslibroot,/Developer/SDKs/MacOSX10.7.sdk" + export CFLAGS="-g -isysroot /Developer/SDKs/MacOSX10.7.sdk -arch i386" + export LDFLAGS="-syslibroot,/Developer/SDKs/MacOSX10.7.sdk" -./configure --disable-dependency-tracking --enable-static=yes --enable-shared=no \ - --target=i386-apple-darwin8 --host=powerpc-apple-darwin8 --build=i386-apple-darwin8 + ./configure --disable-dependency-tracking --enable-static=yes --enable-shared=no \ + --target=i386-apple-darwin8 --host=powerpc-apple-darwin8 --build=i386-apple-darwin8 You will need to reverse the powerpc and i386 parameters everywhere to build PPC on an Intel machine. diff --git a/docs/osx/readme.txt b/docs/osx/readme.txt index 766c099a10..28c11e87a0 100644 --- a/docs/osx/readme.txt +++ b/docs/osx/readme.txt @@ -2,9 +2,9 @@ Welcome to wxWidgets/Mac More Information is available from the wxWidgets project home page at -https://www.wxwidgets.org +https://www.wxwidgets.org -For more information, please see install.txt and the manuals. +For more information, please see install.md and the manuals. Please send problems concerning installation, feature requests, bug reports or comments to the wxWidgets users list. Information