Migration Guide
Migrating from version 2017-08-10
Remove unique instance code from rc.lua
Unique instance support has been moved to a module. To update, follow these steps:
- Remove the two
if unique then ... endblocks from yourrc.lua. - Add
require "unique_instance"to yourrc.lua, before all otherrequirestatements.
Move globals settings to rc.lua
The globals.lua configuration file has been removed. In its place
is the new settings module, which provides a central place to set
settings with validation and domain-specific setting support.
All modified fields of the globals table need to be migrated to
equivalent settings. When starting luakit, a warning will be logged
for each setting that must be migrated, showing the new code for that
setting.
Remove old configuration files
The window.lua, webview.lua, and webview_wm.lua configuration
files have been made core modules, and any configuration files are
ignored.
If you have made extensive changes to these files, please open an issue
on the luakit GitHub repository to discuss adding new APIs to support
your changes. As an interim solution, you can still override the core
modules by modifying the package.path variable; note that this is
not officially supported, and unless you carefully keep your modified
files synchronized with new changes, unpredictable errors may result.
Migrating from a pre-WebKit2 Version
The latest luakit release is built around the WebKit 2 APIs. Changes in the APIs provided by WebKit have necessitated some corresponding changes in luakit's APIs, and as a result there have been many breaking changes.
Remove any existing personal configuration
Luakit's configuration file has seen many changes; as a result, you are likely to encounter errors unless you remove any personal configuration for a previous luakit version. You may wish to back up your configuration if you have made extensive changes; such changes can then be merged in to the up-to-date configuration.
Note: It is inadvisable to copy luakit's entire system configuration directory to make a personal copy, as was previously encouraged. This makes it harder for you to upgrade luakit, as you have more files to merge upstream changes into, and you are more likely to experience errors caused by such upstream changes (until those changes are merged with your personal configuration).
Migrate personal key bindings
The binds.lua and modes.lua configuration files have been removed.
It is no longer necessary to copy the entire set of key bindings to
your configuration to change or add just a few key bindings. Instead,
use add_binds and remove_binds to add and remove key
bindings.
Remove use of module() in scripts
Lua's module() function sets a global variable of the same name as the module,
which pollutes the global namespace for all Lua code. A recent effort
was made to remove all usage of module() within Luakit. While module() is
still accessible, its use is not advised.
This has the side effect that many variables once assumed globally accessible
must now be retrieved with a call to require().
Remove use of init_funcs
The window and webview classes previously had a method of registering
functions to be called when a new window or webview was created, called
init_funcs. This has been removed entirely in favor of a signals-based
approach, which does not run the risk of name collision.
The window and webview classes now emit the "init" signal. To replace any
functions previously registered via init_funcs, add a signal handler:
webview.add_signal("init", function (view)
-- Do something with new view
end)
One important difference between the "init" signal and the
init_funcs method is that the former no longer passes the current
window table w as a parameter. This is because views may be moved
between windows (for example, with the :tabdetach command).
The window class also emits a "build" signal before emitting the
init signal. This provides an opportunity for modules to change the layout and
arrangement of widgets within the window, before the "init" signal is emitted.
Remove use of local capi table
Some old code wraps references to several builtin variables in a capi table.
This does not namespace the builtin variables wrapped in this manner; they are
still globally accessible (and otherwise could not be wrapped in this fashion),
and so all this accomplishes is the addition of more code, more indirection, and
confusion about luakit's and Lua's namespacing rules, for no actual advantage.
As such, it is advised to remove any such wrapper tables, and reference the globally-accessible builtin luakit libraries directly.
Use styles module instead of user_stylesheet_uri
The styles module offers a replacement for the old user_stylesheet_uri
property, which was used to set a stylesheet to customize web behavior. This
module has a number of advantages over the old method, including the ability to
enable/disable stylesheets at runtime, the ability to have multiple stylesheets,
and the ability to use @-moz-document rules in your stylesheets.
- Ensure the
stylesmodule is enabled in yourrc.lua. - Locate the
stylessub-directory within luakit's data storage directory. Normally, this is located at~/.local/share/luakit/styles/. Create the directory if it does not already exist. - Move any CSS rules to a new file within that directory. In order for the
stylesmodule to load the stylesheet, the filename must end in.css. - Make sure you specify which sites your stylesheet should apply to. The way to
do this is to use
@-moz-documentrules. The Stylish wiki page Applying styles to specific sites may be helpful. - Run
:styles-reloadto detect new stylesheet files and reload any changes to existing stylesheet files; it isn't necessary to restart luakit.