From f0551b8645d9e3babf35e40fbc74c02ec8990e58 Mon Sep 17 00:00:00 2001 From: Aqua-sama Date: Fri, 22 Sep 2017 16:44:19 +0200 Subject: Updated documentation --- docs/manual/Building.Compiling.md | 44 +++++++++++++++++++ docs/manual/Building.Dependencies.md | 15 +++++++ docs/manual/Building.Packaging.md | 16 +++++++ docs/manual/Building.md | 26 ++++++++++++ docs/manual/Contributing.Bugs.md | 20 +++++++++ docs/manual/Contributing.Code.md | 35 +++++++++++++++ docs/manual/Contributing.Style.md | 70 ++++++++++++++++++++++++++++++ docs/manual/Contributing.md | 1 + docs/manual/Features.1.0.md | 82 ++++++++++++++++++++++++++++++++++++ docs/manual/Features.md | 1 + docs/manual/Introduction.md | 1 + docs/manual/Quickstart.md | 4 ++ docs/manual/SUMMARY.md | 14 ++++++ 13 files changed, 329 insertions(+) create mode 100644 docs/manual/Building.Compiling.md create mode 100644 docs/manual/Building.Dependencies.md create mode 100644 docs/manual/Building.Packaging.md create mode 100644 docs/manual/Building.md create mode 100644 docs/manual/Contributing.Bugs.md create mode 100644 docs/manual/Contributing.Code.md create mode 100644 docs/manual/Contributing.Style.md create mode 100644 docs/manual/Contributing.md create mode 100644 docs/manual/Features.1.0.md create mode 100644 docs/manual/Features.md create mode 100644 docs/manual/Introduction.md create mode 100644 docs/manual/Quickstart.md create mode 100644 docs/manual/SUMMARY.md (limited to 'docs/manual') diff --git a/docs/manual/Building.Compiling.md b/docs/manual/Building.Compiling.md new file mode 100644 index 0000000..bf6637e --- /dev/null +++ b/docs/manual/Building.Compiling.md @@ -0,0 +1,44 @@ +# Compiling + +## Creating qbs configuration +Before you can build anything with qbs, you need to set up the compiler +toolchain as well as Qt. + +``` +qbs setup-toolchains --detect +qbs setup-qt /usr/bin/qmake-qt5 qt5 +``` + + +## Compiling + +* Create a build folder +``` +[smolbote repo]$ mkdir ../build +``` + +* Run qbs +``` +[smolbote repo]$ qbs build -d ../build profile:qt5 release +``` +This installs the files to ../build/release/install-root. + +* Run +``` +[smolbote repo]$ qbs run -d ../build -p poi profile:qt5 release +``` + +## mach +mach is a helper script that can build and run smolbote. + +#### setup +./mach setup creates a qbs configuration in :settingsDir, +by default ../build/config. + +You can edit this using qbs-config-ui --settings-dir ../build/config. + +#### run + +#### clean + +#### build diff --git a/docs/manual/Building.Dependencies.md b/docs/manual/Building.Dependencies.md new file mode 100644 index 0000000..a506958 --- /dev/null +++ b/docs/manual/Building.Dependencies.md @@ -0,0 +1,15 @@ +# Dependencies + +### Libraries +- [Qt](https://www.qt.io/) + - at least 5.9 + - core, widgets + - webengine, webenginewidgets +- [libconfig](http://hyperrealm.com/libconfig/libconfig.html) + +### Tools +* A working compiler + - gcc or clang on Linux + - msvc on Windows due to QtWebEngine +* qbs + - minimal version 1.8.0 diff --git a/docs/manual/Building.Packaging.md b/docs/manual/Building.Packaging.md new file mode 100644 index 0000000..c88eab0 --- /dev/null +++ b/docs/manual/Building.Packaging.md @@ -0,0 +1,16 @@ +# Packaging + +## Source Tarball + +1. Get source code from the repository +> git archive --format=tar HEAD > head.tar + +2. Compress with lzip +> lzip -9 --force --output=head.tar.lz head.tar + +3. Generate checksum +> sha512sum --binary head.tar.lz > head.tar.lz.sha512 + +## makepkg + +A PKGBUILD is provided in linux/makepkg/PKGBUILD. diff --git a/docs/manual/Building.md b/docs/manual/Building.md new file mode 100644 index 0000000..aa5c1f4 --- /dev/null +++ b/docs/manual/Building.md @@ -0,0 +1,26 @@ +# Building + +### Notes (TODO: move) +* Windows: MSVC compiler is required because of QtWebEngine dependency +* Windows: Passing the -v or -h parameters creates a dialog box instead of +writing the output to stdout. This is Qt behaviour. +* Windows: Use windeployqt.exe to collect the libraries +``` +QT_DIR\QT_VER\msvc2015_64\windeployqt.exe build-PROFILE\release\qtbrowser.exe +``` +* grsecurity: You may need to exception qbs. + +An optional system proxy should be picked up automatically. However, for proxies +that require a username or password, you need to connect to +QWebEnginePage::proxyAuthenticationRequired. + +Qt WebEngine Widgets uses the Qt Quick Scene Graph to compose the page. +Therefore, OpenGL support is required. +And that's also why QML is a dependancy. + +To use clang with QtCreator, you need to change the compiler in +Build & Run » Kits, not the qbs profile. + + + +[1]: https://doc.qt.io/qbs/index.html diff --git a/docs/manual/Contributing.Bugs.md b/docs/manual/Contributing.Bugs.md new file mode 100644 index 0000000..9904273 --- /dev/null +++ b/docs/manual/Contributing.Bugs.md @@ -0,0 +1,20 @@ +# Reporting bugs + +Please include the following when reporting bugs: +* Operating system used +* Version of Qt used +* Detailed explanation of the bug: + * what was done + * what was expected + * what happened + +An example of a bad bug report is: +> Something happened, and what I pressed the button it broke. + +An exmaple of a good bug report is: +> When I opened the Page menu and pressed Print to PDF, nothing happened. + +You can fill out this template when submitting a bug report +> I'm using (Windows? Linux?) +> +> The smolbote version is (0.1? 0.2? 1.0?) diff --git a/docs/manual/Contributing.Code.md b/docs/manual/Contributing.Code.md new file mode 100644 index 0000000..419a08c --- /dev/null +++ b/docs/manual/Contributing.Code.md @@ -0,0 +1,35 @@ +# Before you submit + +## Licensing +Smolbote is licensed under GPLv3. Your code needs to be compatible with it, and +have a license header. + +A sample GPLv3 header is included in docs/header-gpl3.txt + +The provided pre-commit hook uses the following regular expression to check for +a license: +```ruby +/Copyright\s\(C\)\s(\d{4}\s*-\s*){0,1}(#{Time.now.year})/ +``` + +## Style +Please use the [One True Brace style](https://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS_.28OTBS.29). +Tabs are 4 spaces. + +For ease of use, you can set the following astyle configuration: +``` +--style=otbs +--attach-namespaces +--attach-inlines +--indent=spaces=4 +``` + +## Format patch for email +```sh +git format-patch hash +``` +where _hash_ is the commit immediately prior to the commit or series of commits +you want to submit. + +Attach the patch file and email it to _aqua at iserlohn-fortress.net_. If +possible, GPG sign the email. diff --git a/docs/manual/Contributing.Style.md b/docs/manual/Contributing.Style.md new file mode 100644 index 0000000..1ab6b17 --- /dev/null +++ b/docs/manual/Contributing.Style.md @@ -0,0 +1,70 @@ +# Code style + +## Guidelines +* Use generic formats +* Where possible, use QVector over QList: +http://lists.qt-project.org/pipermail/development/2017-March/029040.html + +## Versioning + +#### Major version +Changed infrequently and almost entirely out of foppery and whim. + +#### Minor version +Milestone of multiple features. + +#### Revision +Major bugfixes and each new feature should get a revision. + +### Branching +* master - main branch, should be kept up-to-date, and have only working code +* next - next stable release preparation, mostly for bugfixes +* development - development branch, anything goes there + +### Folder structure + + folder | description + ------ | ----------- +/src | source code +/src/widgets | subclassed Qt widgets +/src/formats | file format parsing (toml, xbel) +/src/forms | Qt UI forms and classes +/src/webengine | QWebEngine subclasses +/test | test run location, mainly for QtCreator + + +## clazy +You can use [clazy](https://github.com/KDE/clazy) to check Qt semantics. +Requires clang. + +To set check levels, set the CLAZY_CHECKS environment variable to 'level0,level1', etc. + +### Setting up in QtCreator +The simplest way to set it up is to use _clazy_ instead of _clang_. + +1. Go to Tools » Options » Build & Run » Compilers +2. Clone the clang compiler of your choice +3. Set _Compiler path_ to _/usr/bin/clazy_ + +This will update the qbs profile that QtCreator uses. + +### Reducing clazy noise +If you want to suppress warnings from headers of Qt or 3rd party code, include +them with -isystem instead of -I. To do this, you have to +[modify your Qt profile](clazy-sysincludes) like this: + +Find the profile's search path: +```sh +$ qbs config --list profiles.qt562.preferences +profiles.qt562.preferences.qbsSearchPaths: "/home/someone/.config/QtProject/qbs/1.9.0/profiles/qt562" +``` + +Replace cpp.includePaths with cpp.systemIncludePaths in the Qt modules of that +profile: + +```sh +$ find /home/someone/.config/QtProject/qbs/1.9.0/profiles/qt562/modules/Qt/ -name '*.qbs' | xargs -n1 sed -i s/cpp\.includePaths/cpp.systemIncludePaths/ +``` + +[clazy-sysincludes]: http://lists.qt-project.org/pipermail/qbs/2017-April/001709.html + diff --git a/docs/manual/Contributing.md b/docs/manual/Contributing.md new file mode 100644 index 0000000..854139a --- /dev/null +++ b/docs/manual/Contributing.md @@ -0,0 +1 @@ +# Contributing diff --git a/docs/manual/Features.1.0.md b/docs/manual/Features.1.0.md new file mode 100644 index 0000000..31ad978 --- /dev/null +++ b/docs/manual/Features.1.0.md @@ -0,0 +1,82 @@ +# Version 1.0 +* Profiles + - Application-level profile manager + - System-level and user-level profile config, with per-profile overrides [todo] +* Configuration + - Default system-level config and user-level overrides [todo] +* Cookies + - Filter list similar to the URL filter list [todo] +* Tabs + - Moving tabs between windows [todo] + - Tab context menu [todo] +* Page actions + - Search [todo] + - Zoom [todo] + - Print [todo] +* Navigation toolbar + - Back and Forward history [todo] + +## Overall design of smolbote + +The aim of smolbote is to be a lightweight and fast, to the point web browser. + +### How smolbote works [TODO] + +0. Launch +1. Check for other instance, unless otherwise specified + - If other instance is found, pass the parameters to it and quit + - Else, create a new instance +2. Create application object + - Read configuration + _ Create profiles +3. Pass parameters to application object + - Create main window if there isn't one + - open URLs + +### main() and smolmain() [TODO] + +The main() function should contain all code to start up, check for another +running instance, and if necessary pass the parameters to the other instance. + +The smolmain() function should contain code to create a new instance based on +the parameters passed. + +IPC should be done with QLocalSocket. + +### Dockable windows + +### Folder structure + +- data/ - Any resource files (defaults, icons, etc) +- docs/ - Where all the documentation lives +- src/ - Source code +- test/ - Testing grounds +- tools/ - Hooks, qbs helpers, updater + +### Libraries used +All 3rd-party libraries should be placed in src/3rd-party/library-name, together +with their corresponding license file. The license file should start with the +library name and repository location. + +- tinytoml + +## Components +Components should, when possible, be split off into self-contained static +libraries. This is to reduce recompile times. + +### Navigation +Includes the Address bar (URLLineEdit). + +### Bookmarks [TODO] + +- [TODO] Bookmark location should be read from profile, with a default in the config +- [TODO] Split off xbel implementation into a library +- [TODO] BookmarksLibrary API + +### History + +History is managed by QtWebEngine. + +### Cookies + +Cookies are managed by QtWebEngine. diff --git a/docs/manual/Features.md b/docs/manual/Features.md new file mode 100644 index 0000000..ead0223 --- /dev/null +++ b/docs/manual/Features.md @@ -0,0 +1 @@ +# Features diff --git a/docs/manual/Introduction.md b/docs/manual/Introduction.md new file mode 100644 index 0000000..e10b99d --- /dev/null +++ b/docs/manual/Introduction.md @@ -0,0 +1 @@ +# Introduction diff --git a/docs/manual/Quickstart.md b/docs/manual/Quickstart.md new file mode 100644 index 0000000..9cbcda0 --- /dev/null +++ b/docs/manual/Quickstart.md @@ -0,0 +1,4 @@ +# Getting started + +- Installing and running smolbote +- Configuration files diff --git a/docs/manual/SUMMARY.md b/docs/manual/SUMMARY.md new file mode 100644 index 0000000..5362502 --- /dev/null +++ b/docs/manual/SUMMARY.md @@ -0,0 +1,14 @@ +# Summary + +- [Introduction](./Introduction.md) +- [Getting started](./Quickstart.md) +- [Features](./Features.md) + - [1.0](./Features.1.0.md) +- [Building](./Building.md) + - [Dependencies](./Building.Dependencies.md) + - [Compiling](./Building.Compiling.md) + - [Packaging](./Building.Packaging.md) +- [Contributing](./Contributing.md) + - [Reporting bugs](./Contributing.Bugs.md) + - [Code style](./Contributing.Style.md) + - [Before you submit](./Contributing.Code.md) -- cgit v1.2.1