aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAqua-sama <aqua@iserlohn-fortress.net>2017-09-22 16:44:19 +0200
committerAqua-sama <aqua@iserlohn-fortress.net>2017-09-22 16:44:19 +0200
commitf0551b8645d9e3babf35e40fbc74c02ec8990e58 (patch)
tree140ce0b81f1da4a385a02709e03e9a734c0ee420
parentFixed bug with starting up if the local socket wasn't cleaned up (diff)
downloadsmolbote-f0551b8645d9e3babf35e40fbc74c02ec8990e58.tar.xz
Updated documentation
-rw-r--r--BUILDING.md103
-rw-r--r--docs/manual.md12
-rw-r--r--docs/manual/Building.Compiling.md44
-rw-r--r--docs/manual/Building.Dependencies.md15
-rw-r--r--docs/manual/Building.Packaging.md16
-rw-r--r--docs/manual/Building.md26
-rw-r--r--docs/manual/Contributing.Bugs.md20
-rw-r--r--docs/manual/Contributing.Code.md35
-rw-r--r--docs/manual/Contributing.Style.md (renamed from CONTRIBUTING.md)56
-rw-r--r--docs/manual/Contributing.md1
-rw-r--r--docs/manual/Features.1.0.md82
-rw-r--r--docs/manual/Features.md1
-rw-r--r--docs/manual/Introduction.md1
-rw-r--r--docs/manual/Quickstart.md4
-rw-r--r--docs/manual/SUMMARY.md14
-rw-r--r--linux/makepkg/PKGBUILD51
-rwxr-xr-xmach33
-rw-r--r--smolbote.qbs5
18 files changed, 343 insertions, 176 deletions
diff --git a/BUILDING.md b/BUILDING.md
deleted file mode 100644
index d701a7d..0000000
--- a/BUILDING.md
+++ /dev/null
@@ -1,103 +0,0 @@
-## Building
-
-### Dependencies
-* Qt, over 5.9, up-to-date Qt version recommended
-* qbs, over 1.8.0
-
-### Tools
-* Qt: core, widgets, webengine, webenginewidgets
-* gcc or clang on linux, msvc on windows
-* qbs
-
-### Configuration
-* Set up Qbs
-```
-qbs setup-toolchains --detect
-qbs setup-qt /usr/bin/qmake-qt5 qt5
-```
-For more information on qbs, refer to the [Qbs manual][1], sections Configuring
-and Managing Qt versions.
-
-### 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.
-
-* Test run (optional)
-```
-[smolbote repo]$ qbs run -d ../build -p poi profile:qt5 release
-```
-
-### Installing
-* With qbs
-```
-[smolbote repo]$ sudo qbs install -d build --no-build --install-root /usr/local --settings-dir /home/usr/.config/QtProject/qbs/1.7.1 profile:qt5 release"
-```
-
-### Notes
-* 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.
-
-
-## Packaging
-
-### Tarball
-
-* Creating a tarball:
-```
-tar -I"lzip -9" -cf smolbote-$(git describe --tags).tar.lz --directory=../build/release/install-root . --owner=user:1000 --group=users:1000
-```
-
-* Signing a tarball:
-```
-gpg -u $email -b --armor $tarball
-```
--u, --local-user name
-> Use name as the user ID to sign. This option is silently ignored for the list
-commands, so that it can be used in an options file.
--b, --detach-sign
-> Make a detached signature.
---armor
-> Create a human-readable signature
-
-* Verify signature:
-```
-gpg --verify $signature $tarball
-```
-
-* Creating checksum:
-```
-sha512sum --binary $tarball* > $tarball.sha512
-```
-
-* Verifying checksum:
-```
-sha512sum --check $tarball.sha512
-```
-
-[1]: https://doc.qt.io/qbs/index.html
diff --git a/docs/manual.md b/docs/manual.md
deleted file mode 100644
index 2c827fd..0000000
--- a/docs/manual.md
+++ /dev/null
@@ -1,12 +0,0 @@
-### Command-line parameters
- Parameter | Description | Usage
------------------|---------------------------------|-------
--h | Display help information |
--v, --version | Display version information |
--c, --config | Set a custom configuration file |
---default-config | Print default configuration | Useful for writing user overrides.
--p, --profile | Select a profile |
--n, --no-plugins | Don't load plugins on startup |
---new-instance | Skip instance check on startup |
---in-new-window | Open URL in a new window |
---in-new-tab | Open URL in a new tab |
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/CONTRIBUTING.md b/docs/manual/Contributing.Style.md
index 5e4cdb2..1ab6b17 100644
--- a/CONTRIBUTING.md
+++ b/docs/manual/Contributing.Style.md
@@ -1,30 +1,11 @@
-## Reporting
+# Code style
-### 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
-
-## Contributing
-
-### General code rules
+## Guidelines
* Use generic formats
-
-### Hooks
-Symlink the hooks:
-```
-[smolbote repo]$ ln -s ../../tools/hooks/pre-commit.rb .git/hooks/pre-commit
-```
-
-### Code
* Where possible, use QVector over QList:
http://lists.qt-project.org/pipermail/development/2017-March/029040.html
-### Versioning
+## Versioning
#### Major version
Changed infrequently and almost entirely out of foppery and whim.
@@ -51,30 +32,23 @@ Major bugfixes and each new feature should get a revision.
/src/webengine | QWebEngine subclasses
/test | test run location, mainly for QtCreator
-### Licensing
-Please include an appropriate license header in any file you add. 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})/
-```
+## clazy
+You can use [clazy](https://github.com/KDE/clazy) to check Qt semantics.
+Requires clang.
-### QtCreator
-* In the project Run Settings set the working directory to _$repo/test_, and the
-command line arguments to _-c poi.conf_.
+To set check levels, set the CLAZY_CHECKS environment variable to 'level0,level1', etc.
-### firejail
-Any submitted modifications should work with the provided firejail profile.
+### Setting up in QtCreator
+The simplest way to set it up is to use _clazy_ instead of _clang_.
-### clazy
-You can use [clazy](clazy-git) to check Qt semantics. Requires 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_
-To easily set check levels, set the CLAZY_CHECKS environment variable to
-'level0,level1', etc.
+This will update the qbs profile that QtCreator uses.
-#### Reducing clazy noise
+### 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:
@@ -92,5 +66,5 @@ profile:
$ 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-git]: https://github.com/KDE/clazy
[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)
diff --git a/linux/makepkg/PKGBUILD b/linux/makepkg/PKGBUILD
new file mode 100644
index 0000000..0d9fc88
--- /dev/null
+++ b/linux/makepkg/PKGBUILD
@@ -0,0 +1,51 @@
+# Maintainer: xiannox <xiannox@iserlohn-fortress.net>
+
+pkgname=smolbote-git
+pkgver=0.1.0
+pkgrel=1
+pkgdesc='Yet another Qt browser'
+url="https://neueland.iserlohn-fortress.net/smolbote"
+
+arch=('x86_64')
+license=('GPL3')
+
+depends=('qt5-base' 'qt5-webengine')
+makedepends=('git' 'qt5-tools' 'qbs')
+
+source=("git+git://neueland.iserlohn-fortress.net/smolbote.git")
+sha512sums=('SKIP')
+
+# qmake location for your Qt version
+# Useful if you have another Qt version installed in a specific location
+_qmake='/usr/bin/qmake-qt5'
+# install root, ex: '/usr' or '/usr/local'
+# Should this install in /usr/bin, or in /usr/local/bin, or perhaps in /somewhere/else/bin?
+_iroot='/usr/local'
+
+pkgver() {
+ cd smolbote
+ echo "$(git describe --long --tags | tr - .)"
+}
+
+prepare() {
+ # Prepare the qbs modules
+ rm -rf config
+ mkdir config
+ qbs-setup-toolchains --settings-dir config --detect
+ qbs-setup-qt --settings-dir config ${_qmake} qt
+
+ # Clear out the build folder
+ rm -rf build
+ mkdir build
+}
+
+build() {
+ cd smolbote
+ qbs build --settings-dir ../config -d ../build profile:qt release
+}
+
+package() {
+ cd smolbote
+ qbs install --settings-dir ../config -d ../build --install-root "${pkgdir}${_iroot}" profile:qt release
+}
+
diff --git a/mach b/mach
index 17cef25..2fce8e9 100755
--- a/mach
+++ b/mach
@@ -4,11 +4,10 @@
require 'optparse'
options = {
- :settings => "#{ENV['HOME']}/.config/QtProject/qbs/1.7.1",
+ :settingsDir => "../build/config",
:profile => 'qt5',
+ :build => 'release',
:buildDir => '../build',
- :installDir => '/usr/local',
- :email => 'xian.nox@gmail.com'
}
OptionParser.new do |opts|
@@ -17,7 +16,7 @@ OptionParser.new do |opts|
opts.on("-h", "--help", "Prints this help") do
puts opts
puts "Options: #{options}"
- puts 'Commands: run, clean, build, install, tarball'
+ puts 'Commands: setup, run, clean, build'
exit
end
@@ -33,25 +32,28 @@ OptionParser.new do |opts|
options[:installDir] = dir
end
+ opts.on("--debug", "Debug build") do
+ options[:build] = 'debug'
+ end
+
+ opts.on("--release", "Release build") do
+ options[:build] = 'release'
+ end
+
end.parse!
if not ARGV.empty? then
ARGV.each do|arg|
case arg
+ when 'setup'
+ system "qbs-setup-toolchains --settings-dir #{options[:settingsDir]} --detect"
+ system "qbs-setup-qt --settings-dir #{options[:settingsDir]} /usr/bin/qmake-qt5 #{options[:profile]}"
when 'run'
- system "qbs run -d #{options[:buildDir]} -p poi profile:#{options[:profile]} release"
+ system "qbs run --settings-dir #{options[:settingsDir]} -d #{options[:buildDir]} -p poi profile:#{options[:profile]} #{options[:build]}"
when 'clean'
- system "qbs clean -d #{options[:buildDir]} profile:#{options[:profile]} release"
+ system "qbs clean --settings-dir #{options[:settingsDir]} -d #{options[:buildDir]} profile:#{options[:profile]} #{options[:build]}"
when 'build'
- system "qbs build -d #{options[:buildDir]} --force-probe-execution profile:#{options[:profile]} release"
- when 'install'
- system "sudo qbs install -d #{options[:buildDir]} --no-build --install-root #{options[:installDir]} --settings-dir #{options[:settings]} profile:#{options[:profile]} release"
- when 'tarball'
- filename = "smolbote-#{`git describe --tags`}.tar.lz".gsub("\n", '')
- system "tar -I\"lzip -9\" -cf #{filename} --directory=#{options[:buildDir]}/release/install-root . --owner=user:1000 --group=users:1000"
- system "gpg -u #{options[:email]} -b #{filename}"
- system "gpg -u #{options[:email]} -b --armor #{filename}"
- system "sha512sum --binary #{filename}* > #{filename}.sha512"
+ system "qbs build --settings-dir #{options[:settingsDir]} -d #{options[:buildDir]} --force-probe-execution profile:#{options[:profile]} #{options[:build]}"
else
puts "Unknown argument #{arg}; use ./mach -h for more details"
end
@@ -60,3 +62,4 @@ if not ARGV.empty? then
else
puts 'No arguments; use ./mach -h for more details'
end
+
diff --git a/smolbote.qbs b/smolbote.qbs
index 045f8ce..4bc1a7d 100644
--- a/smolbote.qbs
+++ b/smolbote.qbs
@@ -52,11 +52,6 @@ Project {
}
}
- // enable clazy if using clang
- Properties {
- condition: cpp.compilerName.contains("clang")
- cpp.cxxFlags: ["-Xclang", "-load", "-Xclang", "ClangLazy.so", "-Xclang", "-add-plugin", "-Xclang", "clang-lazy"]
- }
// global includes
cpp.includePaths: ['src', 'src/3rd-party', 'src/lib']
// global defines