Complete Migration Guide document (cztomczak#293)

cztomczak · cztomczak · commit 430125875518 · 2017-03-24T19:17:49.000+01:00
diff --git a/README.md b/README.md
@@ -58,7 +58,7 @@ See the [Examples-README.md](examples/Examples-README.md) file.
 - Additional documentation is in issues labelled [Knowledge Base](../../issues?q=is%3Aissue+is%3Aopen+label%3A%22Knowledge+Base%22)
 - To search documentation use GitHub "This repository" search
   at the top. To narrow results to documentation only select
-  "Markdown" in the left pane.
+  "Markdown" in the right pane.
 - Wiki pages are deprecated and for v31 only
 
 
diff --git a/docs/Examples.md b/docs/Examples.md
@@ -1,4 +1,4 @@
 # Examples
 
 Examples are available in the examples/ root directory. See
-[Examples-README.md](../examples/Examples-README.md).
+the [Examples-README.md](../examples/Examples-README.md) file.
diff --git a/docs/Migration-guide.md b/docs/Migration-guide.md
@@ -1,12 +1,44 @@
-# Migration guide from v31 to latest v55+ (STILL UNDER WORKS.. #293)
+# Migration guide
+
+This migration guide will get you through to make your code work
+with latest CEF Python. This document includes notable changes
+that were introduced to cefpython and each topic is prefixed
+with version number in which a change was introduced.
+This migration guide doesn't cover all changes required for your
+software to run smoothly. Some changes depend on the GUI framework
+you are using and this guide doesn't cover these. You will have
+to go to the examples/ root directory and see the example for your
+GUI framework. The new examples are very straightforward and include
+many useful comments explaining whys. You will have to get through
+its code and see if anything changed that also requires changes
+in your application.
 
 
 Table of contents:
-* [Distribution packages](#distribution-packages)
-* [Handlers' callbacks and other interfaces](#handlers-callbacks-and-other-interfaces)
+* [v50+ Distribution packages](#v50-distribution-packages)
+* [v50+ Importing the cefpython3 package on Linux](#v50-importing-the-cefpython3-package-on-linux)
+* [v50+ Install X11 error handlers on Linux](#v50-install-x11-error-handlers-on-linux)
+* [v50+ Set window bounds on Linux](#v50-set-window-bounds-on-linux)
+* [v50+ Notify CEF on move or resize events](#v50-notify-cef-on-move-or-resize-events)
+* [v50+ Keyboard focus issues on Linux](#v50-keyboard-focus-issues-on-linux)
+* [v50+ Windows XP and Vista are no more supported](#v50-windows-xp-and-vista-are-no-more-supported)
+* [v50+ Mac 32-bit is no more supported](#v50-mac-32-bit-is-no-more-supported)
+* [v50+ cefbuilds.com is deprected, use Spotify Automated CEF Builds](#v50-cefbuildscom-is-deprected-use-spotify-automated-cef-builds)
+* [v50+ Build instructions and build tools](#v50-build-instructions-and-build-tools)
+* [v51+ Off-screen-rendering: new option "windowless_rendering_enabled"](#v51-off-screen-rendering-new-option-windowless_rendering_enabled)
+* [v51+ Remove LifespanHandler.RunModal](#v51-remove-lifespanhandlerrunmodal)
+* [v51+: BrowserSettings options removed](#v51-browsersettings-options-removed)
+* [v51+ cef.Request.Flags changed](#v51-cefrequestflags-changed)
+* [v51+ Request.GetHeaderMap and SetHeaderMap change](#v51-requestgetheadermap-and-setheadermap-change)
+* [v54+ GTK 3 example doesn't work anymore on Linux](#v54-gtk-3-example-doesnt-work-anymore-on-linux)
+* [v54+ libcef.so library is stripped from symbols on Linux](#v54-libcefso-library-is-stripped-from-symbols-on-linux)
+* [v55+ HTTPS cache problems on pages with certificate errors](#v55-https-cache-problems-on-pages-with-certificate-errors)
+* [v55.3+ Handlers' callbacks and other interfaces](#v553-handlers-callbacks-and-other-interfaces)
+* [v56+ MacOS 10.9+ required to run](#v56-macos-109-required-to-run)
+
 
 
-## Distribution packages
+## v50+ Distribution packages
 
 In latest CEF Python there are only two distribution packages
 available. The first one is a wheel package distributed through
@@ -15,10 +47,14 @@ on Linux). The second one is a setup package available for
 download on the GitHub Releases pages, instructions on how to
 install it are provided in README.txt.
 
+**Windows**
+
 On Windows many of the distribution packages such as MSI, EXE,
 ZIP and InnoSetup files, are no more available. It is too much
 hassle to support these.
 
+**Linux debian package**
+
 On Linux the debian package is not supported anymore. Since
 pip 8.1+ added support for manylinux1 wheel packages, you can
 now easily install cefpython on Linux using the pip tool.
@@ -31,7 +67,173 @@ in an automated manner, it might be reconsidered in the future
 to provide debian packages again.
 
 
-## Handlers' callbacks and other interfaces
+## v50+ Importing the cefpython3 package on Linux
+
+In the past on Linux it was required for the cefpython3 package
+to be imported before any other packages due to tcmalloc global
+hook being loaded. This is not required anymore, tcmalloc is
+disabled by default.
+
+
+## v50+ Install X11 error handlers on Linux
+
+It is required to install X11 error handlers on Linux, otherwise
+you will see 'BadWindow' errors happening - sometimes randomly -
+which will cause application to terminate. Since v56+ x11 error
+handlers are installed automatically by default during the call
+to cef.Initialize(). However sometimes that is not enough like
+for example in the wxpython.py example which requires the x11
+error handlers to be installed manually after wx was initialized,
+and that is because wx initialization had reset x11 error handlers
+that were installed earlier during cef initialization (Issue [#334](../../../issues/334)).
+
+You can install X11 error handlers by calling:
+```
+WindowUtils = cef.WindowUtils()
+WindowUtils.InstallX11ErrorHandlers()
+```
+
+API ref: WindowUtils.[InstallX11ErrorHandlers()](../api/WindowUtils.md#installx11errorhandlers-linux)
+
+
+## v50+ Set window bounds on Linux
+
+It is now required to set window bounds during window "resize",
+"move" and "configure" events on Linux. You can do so by calling:
+
+```
+browser.SetBounds(x, y, width, height)
+```
+
+API ref: Browser.[SetBounds()](../api/Browser.md#setbounds)
+
+
+## v50+ Notify CEF on move or resize events
+
+It is required to notify the browser on move or resize events
+so that popup widgets (e.g. \<select\>) are displayed in the correct
+location and dismissed when the window moves. Also so that
+drag & drop areas are updated accordingly.
+
+```
+browser.NotifyMoveOrResizeStarted()
+```
+
+API ref: Browser.[NotifyMoveOrResizeStarted()](../api/Browser.md#notifymoveorresizestarted)
+
+
+## v50+ Keyboard focus issues on Linux
+
+There several keyboard focus issues on Linux since CEF library
+replaced GTK library with X11 library. Most of these issues are
+fixed in examples by calling SetFocus in LoadHandler.OnLoadStart
+during initial app loading and/or by calling SetFocus in
+FocusHandler.OnGotFocus. This keyboard focus issues need to be
+fixed in usptream CEF. For more details see Issue [#284](../../../issues/284).
+
+
+## v50+ Windows XP and Vista are no more supported
+
+CEF Python v31.2 was the last version to support Windows XP.
+This is due to Chromium/CEF dropping XP support, last version
+that supported XP was CEF v49.
+
+
+## v50+ Mac 32-bit is no more supported
+
+CEF Python v31.2 was the last version to support Mac 32-bit.
+This is due to CEF/Chromium dropping 32-bit support, last version
+that supported 32-bit was CEF v38.
+
+
+## v50+ cefbuilds.com is deprected, use Spotify Automated CEF Builds
+
+The cefbuilds.com site with CEF prebuilt binaries is now deprecated.
+From now on download prebuilt CEF binaries from the Spotify Automated
+CEF Builds:
+
+http://opensource.spotify.com/cefbuilds/index.html
+
+
+## v50+ Build instructions and build tools
+
+Many changes in regards to building CEF and CEF Python has changed.
+There are now new tools in the tools/ root directory that fully
+automate building CEF and CEF Python. CEF Python now provides
+upstream CEF prebuilt binaries and libraries on GitHub Releases
+tagged eg. "v56-upstream". With these binaries you can build
+CEF Python from sources in less than 10 minutes. See the new
+[Build instructions](Build-instructions.md) document.
+
+
+## v51+ Off-screen-rendering: new option "windowless_rendering_enabled"
+
+When using off-screen-rendering you must set the ApplicationSettings
+"windowless_rendering_enabled" option to True. This applies to
+examples such as: Kivy, Panda3D and screenshot example.
+
+API ref: ApplicationSettings.[windowless_rendering_enabled](../api/ApplicationSettings.md#windowless_rendering_enabled)
+
+
+## v51+ Remove LifespanHandler.RunModal
+
+LifespanHandler.RunModal callback is no more available.
+
+
+## v51+: BrowserSettings options removed
+
+The following options were removed from BrowserSettings:
+- user_style_sheet_location
+- java_disabled
+- accelerated_compositing
+- author_and_user_styles_disabled
+
+
+## v51+ cef.Request.Flags changed
+
+The following flags were removed from cef.Request.Flags:
+- AllowCookies
+- ReportLoadTiming
+- ReportRawHeaders
+
+API ref: Request.[GetFlags](../api/Request.md#getflags)
+
+
+## v51+ Request.GetHeaderMap and SetHeaderMap change
+
+GetHeaderMap() will not include the Referer value if any
+and SetHeaderMap() will ignore the Referer value.
+
+API ref: Request.[GetHeaderMap](../api/Request.md#getheadermap)
+
+
+## v54+ GTK 3 example doesn't work anymore on Linux
+
+Currently GTK 3 example is broken on Linux. You can either
+downgrade to an old cefpython v53 (available on GitHub release
+page) or use GTK 2 example. For more details on the problem see
+Issue [#261](../../../issues/261).
+
+
+## v54+ libcef.so library is stripped from symbols on Linux
+
+Symbols useful for debugging are no more available in libcef.so
+shipped with distribution packages on Linux. This is explained
+in details in Issue [#262](../../../issues/262).
+
+
+## v55+ HTTPS cache problems on pages with certificate errors
+
+The fix for HTTPS cache problems on pages with certificate errors
+is no more applied on Windows.
+
+Soon this will fix also won't be applied on Linux anymore when
+cefpython starts using CEF prebuilt binaries from Spotify.
+
+See Issue [#125](../../../issues/125) for more details.
+
+
+## v55.3+ Handlers' callbacks and other interfaces
 
 Since v55.3 all handlers' callbacks and other interfaces such as
 CookieVisitor, StringVisitor and WebRequestClient, are now called
@@ -77,5 +279,6 @@ your code will definitely break, unless you've also used
 "http_code" for argument name.
 
 
+## v56+ MacOS 10.9+ required to run
 
-
+CEF v55 was the last version to support MacOS 10.7.
