webbrowser-app is a lightweight web browser tailored for Ubuntu,
based on the Oxide web engine and using the Ubuntu UI components.
It requires Qt 5.4 to build and run.


= Building =

The build system uses cmake.
To compile, simply invoke cmake and then make:

    $ cmake .
    $ make

The application can also be cross compiled for an ARM target on a X86 host.
To do that, just pass this additional parameter to cmake:

    $ cmake -DCMAKE_TOOLCHAIN_FILE=cmake/ubuntu-arm-linux-gnueabihf.cmake .


= Running =

webbrowser-app can be run from the development branch without the need to
install any files. Just run:

    $ ./src/app/webbrowser/webbrowser-app

The executable accepts command line switches and parameters. To find out which,
just run:

    $ ./src/app/webbrowser/webbrowser-app --help


= Unit tests =

To run the unit tests, you can use the commands below:

    $ make test

      - or -

    $ ctest


= Automated UI tests =

webbrowser-app uses autopilot (https://launchpad.net/autopilot) to test its UI.
To run the tests, you will need to install python3-autopilot and autopilot-qt5.
Then do the following:

    $ cd tests/autopilot/
    $ autopilot3 run webbrowser_app

You can get a list of all available tests with the following command:

    $ autopilot3 list webbrowser_app


= Code coverage =

To generate a report with detailed code coverage, you need to re-run cmake with
"CMAKE_BUILD_TYPE=coverage":

    $ cmake -DCMAKE_BUILD_TYPE=coverage .
    $ make
    $ make test
    $ make coverage

This will generate a coverage report in XML format (coverage.xml) and an
interactive human-readable report in HTML format (coveragereport/index.html).


= Settings =

webbrowser-app supports a limited set of custom settings, persisted on disk in
the following INI-like file:

    $HOME/.config/webbrowser-app/webbrowser-app.conf

The following keys are supported:

 - 'homepage': a URL that the browser will open when launched if no URL is
   specified on the command line

 - 'searchengine': a custom search engine specification, looked up in
   $HOME/.local/share/webbrowser-app/searchengines/{value}.xml and following
   the OpenSearch document description format
   (http://www.opensearch.org/Specifications/OpenSearch/1.1)

 - 'allowOpenInBackgroundTab': whether to offer an option to open a link in a
   new background tab in the contextual menu. Possible values are "true",
   "false", and "default" (which resolves to true on desktop and false on
   mobile).

 - restoreSession: whether to restore the previous browsing session at startup
   (defaults to true)