From d8cc3eeeb55b92b0d7fe9a325937df11c28fbcaa Mon Sep 17 00:00:00 2001 From: Aqua-sama Date: Sun, 12 Jan 2020 17:05:25 +0200 Subject: Update doc/ and move various entries to wiki --- BUGS.md | 14 +++ LICENSE.md | 17 ++- LICENSES/bsl-1.0.txt | 23 ---- LICENSES/lgpl-3.0.txt | 165 ---------------------------- doc/Bugs.asciidoc | 60 ---------- doc/Building.asciidoc | 67 ----------- doc/Building/Breakpad.asciidoc | 44 -------- doc/Building/Windows.asciidoc | 26 ----- doc/Building/meson.asciidoc | 39 ------- doc/Development.asciidoc | 73 ------------ doc/Development/Fuzzing.asciidoc | 49 --------- doc/Development/Hacking.asciidoc | 52 --------- doc/Development/Manual.asciidoc | 11 -- doc/Development/RepositoryCommands.asciidoc | 6 - doc/Development/Session.asciidoc | 19 ---- doc/Development/Translating.asciidoc | 16 --- doc/Development/Updater.asciidoc | 25 ----- doc/Development/git.asciidoc | 10 -- doc/Usage.asciidoc | 21 ---- doc/Usage/CommandLine.asciidoc | 14 --- doc/Usage/Configuration.asciidoc | 14 --- doc/Usage/Filter.asciidoc | 12 -- doc/Usage/Linux.asciidoc | 15 --- doc/Usage/Plugins.asciidoc | 7 -- doc/Usage/Profile.asciidoc | 37 ------- doc/building.md | 59 ++++++++++ doc/contributing.md | 37 +++++++ doc/images/browser-for-fun.png | Bin 186244 -> 0 bytes doc/smolbote.asciidoc | 22 ---- 29 files changed, 117 insertions(+), 837 deletions(-) create mode 100644 BUGS.md delete mode 100644 LICENSES/bsl-1.0.txt delete mode 100644 LICENSES/lgpl-3.0.txt delete mode 100644 doc/Bugs.asciidoc delete mode 100644 doc/Building.asciidoc delete mode 100644 doc/Building/Breakpad.asciidoc delete mode 100644 doc/Building/Windows.asciidoc delete mode 100644 doc/Building/meson.asciidoc delete mode 100644 doc/Development.asciidoc delete mode 100644 doc/Development/Fuzzing.asciidoc delete mode 100644 doc/Development/Hacking.asciidoc delete mode 100644 doc/Development/Manual.asciidoc delete mode 100644 doc/Development/RepositoryCommands.asciidoc delete mode 100644 doc/Development/Session.asciidoc delete mode 100644 doc/Development/Translating.asciidoc delete mode 100644 doc/Development/Updater.asciidoc delete mode 100644 doc/Development/git.asciidoc delete mode 100644 doc/Usage.asciidoc delete mode 100644 doc/Usage/CommandLine.asciidoc delete mode 100644 doc/Usage/Configuration.asciidoc delete mode 100644 doc/Usage/Filter.asciidoc delete mode 100644 doc/Usage/Linux.asciidoc delete mode 100644 doc/Usage/Plugins.asciidoc delete mode 100644 doc/Usage/Profile.asciidoc create mode 100644 doc/building.md create mode 100644 doc/contributing.md delete mode 100644 doc/images/browser-for-fun.png delete mode 100644 doc/smolbote.asciidoc diff --git a/BUGS.md b/BUGS.md new file mode 100644 index 0000000..71db27c --- /dev/null +++ b/BUGS.md @@ -0,0 +1,14 @@ +## QTBUG 62957: databases-incognito and VideoDecodeStats in home +- url: https://bugreports.qt.io/browse/QTBUG-62957 +- workaround: use provided firejail profile + +## QTBUG 65223: loadStarted is emitted twice when loading link with anchor +- url: https://bugreports.qt.io/browse/QTBUG-65223 + +## rcc embeds time in output +- url: https://bugreports.qt.io/browse/QTBUG-62511 +- workaround: pass _'--format-version=1'_ to rcc + +## QWebEngineUrlRequestInterceptor does not allow to pass the Referer header +- url: https://bugreports.qt.io/browse/QTBUG-60203 + diff --git a/LICENSE.md b/LICENSE.md index 7518913..96bcfc3 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,6 +1,6 @@ # smolbote -Copyright (C) 2017 - 2019 aqua +Copyright (C) 2017 - 2020 aqua This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as @@ -19,20 +19,17 @@ along with this program. If not, see . - license: LGPL-3.0 - source code: http://code.qt.io/cgit/ -## boost -- components: program_options -- url: http://www.boost.org/ -- license: BSL-1.0 -- source code: http://www.boost.org/users/download/ +## spdlog +- url: https://github.com/gabime/spdlog +- license: MIT ## SingleApplication - url: https://github.com/itay-grudev/SingleApplication - license: MIT -## KDE Frameworks (optional) -- url: https://community.kde.org/Frameworks -- license: LGPL-2.1 -- source code: https://cgit.kde.org/ +## args +- url: https://github.com/Taywee/args +- license: MIT ## Breakpad (optional) - url: https://chromium.googlesource.com/breakpad/breakpad diff --git a/LICENSES/bsl-1.0.txt b/LICENSES/bsl-1.0.txt deleted file mode 100644 index 36b7cd9..0000000 --- a/LICENSES/bsl-1.0.txt +++ /dev/null @@ -1,23 +0,0 @@ -Boost Software License - Version 1.0 - August 17th, 2003 - -Permission is hereby granted, free of charge, to any person or organization -obtaining a copy of the software and accompanying documentation covered by -this license (the "Software") to use, reproduce, display, distribute, -execute, and transmit the Software, and to prepare derivative works of the -Software, and to permit third-parties to whom the Software is furnished to -do so, all subject to the following: - -The copyright notices in the Software and this entire statement, including -the above license grant, this restriction and the following disclaimer, -must be included in all copies of the Software, in whole or in part, and -all derivative works of the Software, unless such copies or derivative -works are solely in the form of machine-executable object code generated by -a source language processor. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT -SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE -FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, -ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER -DEALINGS IN THE SOFTWARE. diff --git a/LICENSES/lgpl-3.0.txt b/LICENSES/lgpl-3.0.txt deleted file mode 100644 index 0a04128..0000000 --- a/LICENSES/lgpl-3.0.txt +++ /dev/null @@ -1,165 +0,0 @@ - GNU LESSER GENERAL PUBLIC LICENSE - Version 3, 29 June 2007 - - Copyright (C) 2007 Free Software Foundation, Inc. - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - - This version of the GNU Lesser General Public License incorporates -the terms and conditions of version 3 of the GNU General Public -License, supplemented by the additional permissions listed below. - - 0. Additional Definitions. - - As used herein, "this License" refers to version 3 of the GNU Lesser -General Public License, and the "GNU GPL" refers to version 3 of the GNU -General Public License. - - "The Library" refers to a covered work governed by this License, -other than an Application or a Combined Work as defined below. - - An "Application" is any work that makes use of an interface provided -by the Library, but which is not otherwise based on the Library. -Defining a subclass of a class defined by the Library is deemed a mode -of using an interface provided by the Library. - - A "Combined Work" is a work produced by combining or linking an -Application with the Library. The particular version of the Library -with which the Combined Work was made is also called the "Linked -Version". - - The "Minimal Corresponding Source" for a Combined Work means the -Corresponding Source for the Combined Work, excluding any source code -for portions of the Combined Work that, considered in isolation, are -based on the Application, and not on the Linked Version. - - The "Corresponding Application Code" for a Combined Work means the -object code and/or source code for the Application, including any data -and utility programs needed for reproducing the Combined Work from the -Application, but excluding the System Libraries of the Combined Work. - - 1. Exception to Section 3 of the GNU GPL. - - You may convey a covered work under sections 3 and 4 of this License -without being bound by section 3 of the GNU GPL. - - 2. Conveying Modified Versions. - - If you modify a copy of the Library, and, in your modifications, a -facility refers to a function or data to be supplied by an Application -that uses the facility (other than as an argument passed when the -facility is invoked), then you may convey a copy of the modified -version: - - a) under this License, provided that you make a good faith effort to - ensure that, in the event an Application does not supply the - function or data, the facility still operates, and performs - whatever part of its purpose remains meaningful, or - - b) under the GNU GPL, with none of the additional permissions of - this License applicable to that copy. - - 3. Object Code Incorporating Material from Library Header Files. - - The object code form of an Application may incorporate material from -a header file that is part of the Library. You may convey such object -code under terms of your choice, provided that, if the incorporated -material is not limited to numerical parameters, data structure -layouts and accessors, or small macros, inline functions and templates -(ten or fewer lines in length), you do both of the following: - - a) Give prominent notice with each copy of the object code that the - Library is used in it and that the Library and its use are - covered by this License. - - b) Accompany the object code with a copy of the GNU GPL and this license - document. - - 4. Combined Works. - - You may convey a Combined Work under terms of your choice that, -taken together, effectively do not restrict modification of the -portions of the Library contained in the Combined Work and reverse -engineering for debugging such modifications, if you also do each of -the following: - - a) Give prominent notice with each copy of the Combined Work that - the Library is used in it and that the Library and its use are - covered by this License. - - b) Accompany the Combined Work with a copy of the GNU GPL and this license - document. - - c) For a Combined Work that displays copyright notices during - execution, include the copyright notice for the Library among - these notices, as well as a reference directing the user to the - copies of the GNU GPL and this license document. - - d) Do one of the following: - - 0) Convey the Minimal Corresponding Source under the terms of this - License, and the Corresponding Application Code in a form - suitable for, and under terms that permit, the user to - recombine or relink the Application with a modified version of - the Linked Version to produce a modified Combined Work, in the - manner specified by section 6 of the GNU GPL for conveying - Corresponding Source. - - 1) Use a suitable shared library mechanism for linking with the - Library. A suitable mechanism is one that (a) uses at run time - a copy of the Library already present on the user's computer - system, and (b) will operate properly with a modified version - of the Library that is interface-compatible with the Linked - Version. - - e) Provide Installation Information, but only if you would otherwise - be required to provide such information under section 6 of the - GNU GPL, and only to the extent that such information is - necessary to install and execute a modified version of the - Combined Work produced by recombining or relinking the - Application with a modified version of the Linked Version. (If - you use option 4d0, the Installation Information must accompany - the Minimal Corresponding Source and Corresponding Application - Code. If you use option 4d1, you must provide the Installation - Information in the manner specified by section 6 of the GNU GPL - for conveying Corresponding Source.) - - 5. Combined Libraries. - - You may place library facilities that are a work based on the -Library side by side in a single library together with other library -facilities that are not Applications and are not covered by this -License, and convey such a combined library under terms of your -choice, if you do both of the following: - - a) Accompany the combined library with a copy of the same work based - on the Library, uncombined with any other library facilities, - conveyed under the terms of this License. - - b) Give prominent notice with the combined library that part of it - is a work based on the Library, and explaining where to find the - accompanying uncombined form of the same work. - - 6. Revised Versions of the GNU Lesser General Public License. - - The Free Software Foundation may publish revised and/or new versions -of the GNU Lesser General Public License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. - - Each version is given a distinguishing version number. If the -Library as you received it specifies that a certain numbered version -of the GNU Lesser General Public License "or any later version" -applies to it, you have the option of following the terms and -conditions either of that published version or of any later version -published by the Free Software Foundation. If the Library as you -received it does not specify a version number of the GNU Lesser -General Public License, you may choose any version of the GNU Lesser -General Public License ever published by the Free Software Foundation. - - If the Library as you received it specifies that a proxy can decide -whether future versions of the GNU Lesser General Public License shall -apply, that proxy's public statement of acceptance of any version is -permanent authorization for you to choose that version for the -Library. diff --git a/doc/Bugs.asciidoc b/doc/Bugs.asciidoc deleted file mode 100644 index d4ab1ec..0000000 --- a/doc/Bugs.asciidoc +++ /dev/null @@ -1,60 +0,0 @@ -== Reporting bugs - -=== What to include -A bug report should contain these 4 things: - -==== Environment -This includes program version; operating system used; version of Qt or other -libraries; any relevant information if you built from source. - -==== Steps to reproduce -Give detailed steps on how to reproduce the problem. Start from the beginning, -mention the actions involved, and be verbose. - -==== Expected result -It's important to include the result you were expecting, as it might differ -from the way the program was designed to work. - -==== Actual result -It is also important to include a good description of the buggy behaviour -itself as well, because it's possible that following your steps on a different -system doesn't reproduce the issue. - -Send bug reports to _aqua at iserlohn dash fortress dot net_. - -_Adapted from the guide in the texmate repository._ - -== Known bugs - -=== databases-incognito in home -https://bugreports.qt.io/browse/QTBUG-62957 - -=== loadFinished is not always emitted when loading is finished -https://bugreports.qt.io/browse/QTBUG-65223 - -=== QWebEngineView setUrl()/load() methods in some case divide page in two parts -https://bugreports.qt.io/browse/QTBUG-68224 - -Only affects Qt 5.11.0. Set __QTBUG_68224_WORKAROUND__. - -=== rcc embeds time in output -https://bugreports.qt.io/browse/QTBUG-62511 - -=== QWebEngineUrlRequestInterceptor does not allow to pass the Referer header -https://bugreports.qt.io/browse/QTBUG-60203 - -=== Wayland bugs - -=== mainwindow.maximized doesn't work -setWindowState(Qt::WindowMaximized) has no effect on KDE/Wayland: -https://community.kde.org/Plasma/Wayland_Showstoppers - -=== Windows bugs - -=== stdout and stderr -Starting the application with some command-line options (like --version, ---help, etc) causes the application to 'stall' on exit. - -Starting the application from the command prompt returns after launch, but -continues outputting stdout and stderr to it. - diff --git a/doc/Building.asciidoc b/doc/Building.asciidoc deleted file mode 100644 index fc7cc89..0000000 --- a/doc/Building.asciidoc +++ /dev/null @@ -1,67 +0,0 @@ -== Requirements - -[cols="1,1,3"] -|=== -|Name |Version |Notes - -| link:https://www.qt.io/[Qt] -| 5.11.1 or later -| QtWebEngine should be buildable with older versions of Qt. Please use the - latest version. - -| link:http://www.boost.org/[boost] -| Version 1.66 -| Components: program_options - -| link:https://mesonbuild.com/[meson] -| Version 0.48 -| Requires python3 and ninja - -| link:https://github.com/ulfalizer/Kconfiglib[Kconfiglib] -| Version 10.22.1 -| Available on PyPI with 'pip install kconfiglib' - -| A compiler -| C++17 support -| gcc 7+; clang 4+; on Windows only MSVC is supported due to QtWebEngine - -| asciidoc -| -| Only for building manpage - -|=== - -== Building from source -[source, sh] ----- -# clone the repository -git clone https://neueland.iserlohn-fortress.net/gitea/aqua/smolbote.git smolbote.git -cd smolbote.git - -# These two submodules are required -git submodule init -git submodule update 3rd-party/SingleApplication/SingleApplication.git -git submodule update tools/Kconfiglib - -# generate build.ninja -mkdir build -meson build - -# make -ninja ----- - -Run `meson configure` in the build directory to list available options. -For more information on how to use meson, see the meson link:https://mesonbuild.com/Quick-guide.html[quick guide]. - -=== Configuring smolbote -smolbote uses Kconfig to store and customize default application settings such -as keyboard shortcuts and paths. You can edit these settings using 'menuconfig' -in the repository root. - -When building, tools/config.py is used to load `$platform-name/.config` and -generate a header file. - -// Compiling on Windows -include::Building/Windows.asciidoc[] - diff --git a/doc/Building/Breakpad.asciidoc b/doc/Building/Breakpad.asciidoc deleted file mode 100644 index aa2642e..0000000 --- a/doc/Building/Breakpad.asciidoc +++ /dev/null @@ -1,44 +0,0 @@ -== Breakpad - -=== Enabling breakpad -Use the `-DBreakpad=enabled` option. This requires Breakpad be installed as a package. - -=== Building breakpad on linux -[source, sh] ----- -# Get the missing linux syscall support header -if [ ! -f breakpad.git/src/third_party/lss/linux_syscall_support.h ]; then - mkdir -p breakpad.git/src/third_party/lss - curl -L https://chromium.googlesource.com/linux-syscall-support/+/master/linux_syscall_support.h?format=TEXT | base64 --decode > breakpad.git/src/third_party/lss/linux_syscall_support.h -fi - -buildpath=$(pwd)/build -if [ ! -d $buildpath ]; then - mkdir $buildpath -fi - -installpath=$(pwd)/install -if [ ! -d $installpath ]; then - mkdir $installpath -fi - -cd $buildpath -../breakpad.git/configure --prefix=$installpath -make -make install ----- - -=== Producing symbols -[source, sh] ----- -tools/linux/dump_syms/dump_syms ./poi > poi.sym -head -n1 poi.sym -mkdir -p ./symbols/poi/ -mv poi.sym ./symbols/poi/ ----- - -=== Processing minidump -[source, sh] ----- -processor/minidump_stackwalk minidump.dmp ./symbols ----- diff --git a/doc/Building/Windows.asciidoc b/doc/Building/Windows.asciidoc deleted file mode 100644 index 4c1fc20..0000000 --- a/doc/Building/Windows.asciidoc +++ /dev/null @@ -1,26 +0,0 @@ -== Building on Windows -[source, bat] ----- -set INSTALL_DIR="C:\projects\smolbote-install" -mkdir %INSTALL_DIR% - -mkdir C:\projects\smolbote-build -cd C:\projects\smolbote-build - -set QT="C:\Qt\5.11\msvc2017_64" -set BOOST_ROOT="C:\Libraries\boost_1_66_0" -set BOOST_LIBDIR="C:\Libraries\boost_1_66_0\lib64-msvc-14.1" - -cmake -G "Visual Studio 15 2017 Win64" -DCMAKE_BUILD_TYPE=Release - -DCMAKE_INSTALL_PREFIX=%INSTALL_DIR% - -DCMAKE_PREFIX_PATH=%QT%;%BOOST_ROOT% - -DBOOST_ROOT=%BOOST_ROOT% -DBOOST_LIBRARYDIR=%BOOST_LIBDIR% -DBoost_USE_STATIC_LIBS=On - C:\projects\smolbote - -cmake --build . --target poi --config Release -cmake --build . --target install --config Release -cd %INSTALL_DIR% -C:\Qt\5.11\msvc2017_64\bin\windeployqt.exe bin\poi.exe - -7z a C:\projects\smolbote\build.7z %INSTALL_DIR% ----- diff --git a/doc/Building/meson.asciidoc b/doc/Building/meson.asciidoc deleted file mode 100644 index 255e0ad..0000000 --- a/doc/Building/meson.asciidoc +++ /dev/null @@ -1,39 +0,0 @@ -==== Setting compiler -Compiler can only be set when initially configuring the build, and cannot be -changed with --reconfigure: - -[source, sh] ----- -export CXX="ccache clang++" -meson build-path ----- - -==== Setting linker -[source, sh] ----- -build% meson configure -Dcpp_link_args='-fuse_ld=gold' ----- - -==== Listing build options -[source, sh] ----- -build% meson configure ----- - -==== Changing build options -[source, sh] ----- -build% meson configure -D= -# for example: -build% meson configure -DPlasma=enabled ----- - -==== Prevent meson from downloading wraps -During configure, meson can download missing dependencies on its own using -wraps. To disable this, pass '--wrap-mode=nodownload' during the configure -phase: -[source, sh] ----- -repo% meson --wrap-mode=nodownload build-path ----- - diff --git a/doc/Development.asciidoc b/doc/Development.asciidoc deleted file mode 100644 index 1ef2ded..0000000 --- a/doc/Development.asciidoc +++ /dev/null @@ -1,73 +0,0 @@ -== Guidelines - -smolbote is written under the C++17 standard, without any compiler-specific -extensions. Source code should be kept as platform-agnostic as possible. - -=== General -* All behaviour, where possible, should be configurable. -* Configuration is stored in plaintext files, and option names should be as - self-descriptive as possible. -* Use sane defaults. Normally, the program should "just work". - -=== Qt -* Check pointers with Q_CHECK_PTR. -* Use the Qt5 signal/slot syntax (&Class::method) over the old string-based - syntax (SIGNAL/SLOT). This enables compile-time connect checks. -* Prefer QVector over QList: http://lists.qt-project.org/pipermail/development/2017-March/029040.html - -=== Setting linker -Meson has no environment variable to set the linker (link:https://github.com/mesonbuild/meson/issues/3597[issue]). - -Instead, this can be done using the cpp_link_args: -[source, sh] ----- -build% meson configure -Dcpp_link_args='-fuse-ld=gold' ----- - -=== clazy -You can use https://github.com/KDE/clazy[clazy] to check Qt semantics. - -clazy is a drop-in replacement for clang. To set check levels, set the -CLAZY_CHECKS environment variable to 'level0,level1', etc. - -== Licensing -Smolbote is licensed under GPLv3 _only_, and explicitly does not use any -self-updating "-or-later" licensing. Your code needs to be compatible with it, -and have a license header in the style used by the project. - -Interfaces (located in include/) should be licensed under MIT. This is to allow -more license compatibility for plugins. - -=== SPDX-License-Identifier -A full list of license identifiers can be found on https://spdx.org/licenses/[the SPDX website]. - -== Style -There is a clang-format style in .clang-format. - -== Format patch for email - -[source, sh] ----- -git format-patch $from..$to ----- - -This will give you one patch per commit. If you want to merge all of them into -a single patch, you can merge the commits using rebase: - -[source, sh] ----- -git rebase --interactive ----- - -Alternatively, replay all your commits from the commit before $from on a new -branch: - -[source, sh] ----- -git branch delivery X -git checkout delivery -git merge --squash master -git format-patch HEAD ----- - -Email patches to _aqua at iserlohn dash fortress dot net_. diff --git a/doc/Development/Fuzzing.asciidoc b/doc/Development/Fuzzing.asciidoc deleted file mode 100644 index 0981f1a..0000000 --- a/doc/Development/Fuzzing.asciidoc +++ /dev/null @@ -1,49 +0,0 @@ -=== Setup -Required packages: afl - -==== Compiling Qt -This will build an instrumented Qt: - -[source, sh] ----- -export CC=$(which afl-gcc) -export CXX=$(which afl-g++) -./configure ... -make ----- - -=== Running the fuzzer -[source, sh] ----- -cd /sys/devices/system/cpu -su -echo performance | tee cpu*/cpufreq/scaling_governor -exit - -cd $testdir -afl-fuzz -m 512 -t 40 -i $input -o $output -- $testexe @@ - -# see for available scaling_governor values: -cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_governors - -cd /sys/devices/system/cpu -su -echo powersave | tee cpu*/cpufreq/scaling_governor -exit ----- - -The $input directory contains your reference input files, while the findings of the fuzzers will be written in $output. - -@@ gets replaced by the name of a file generated by AFL, containing the mutated input. - -=== Using ramdisk for tests -[source, sh] ----- -$ mkdir afl -# mount -t tmpfs -o size=1024M tmpfs afl/ -$ cd afl/ -$ afl-fuzz -i inputs -o findings ... ----- - -=== Sources -1. https://www.kdab.com/fuzzing-qt-fun-profit/ diff --git a/doc/Development/Hacking.asciidoc b/doc/Development/Hacking.asciidoc deleted file mode 100644 index d0332e9..0000000 --- a/doc/Development/Hacking.asciidoc +++ /dev/null @@ -1,52 +0,0 @@ -== C++ Performance -(Adapted from CppCon2016 Practical Performance Practices) -https://florianjw.de/en/cpp_coding_standard.html - -- Prefer std::array, then std::vector -- Construct and initialize in one step -- Use const always when possible -- To enable const with complex initialization, use lambdas -- Don't recalculate values that only need to be calculated once -- Don't disable move operations - moving is more efficient than copying -- Avoid shared_ptr copies unless really needed -- Prefer returning unique_ptr from factories -- Use '\n' instead of std::endl -- Use lambdas - they have no overhead compared to direct functions -- final can help the compiler optimize virtual function calls -- Code branches are expensive - -=== Smaller code is faster code - -=== Do one thing and do it well -Simple code is easy to understand, easy to maintain, and as such lead to less bugs. - -=== Only use text formats -They can be edited both by humans and by programs. Use generic formats (ini, json, etc.) instead of custom ones. - -=== Document your changes -Don't do this just for others, do it for your future self. - -== Useful compiler options -- -fuse-ld=gold -- -Wold-style-cast - -=== Setting in meson -Compiler arguments are free-form comma-separated list. -meson configure -Dcpp_args="-Wold-style-cast" -meson configure -Dcpp_link_args="-fuse-ld=gold" - -== C++ Coding Standard - -=== Naming Conventions -- Naming uses camelCase -- Private attributes are prefixed with 'm_'. -- Include guards should be named SMOLBOTE__H - -=== Compiler -- Use the highest sane warning level. - -=== Resource management -- Manage your resources with RAII (Resource Acquisition Is Initialization). - -=== Functions -- Try to keep the complexity low and the body short. diff --git a/doc/Development/Manual.asciidoc b/doc/Development/Manual.asciidoc deleted file mode 100644 index 6e5a39f..0000000 --- a/doc/Development/Manual.asciidoc +++ /dev/null @@ -1,11 +0,0 @@ -== manpage - -=== Generating manpage -[code, sh] ----- -# with asciidoc -a2x --format=manpage doc/smolbote.7.asciidoc - -# with asciidoctor -asciidoctor --backend=manpage doc/smolbote.7.asciidoc ----- diff --git a/doc/Development/RepositoryCommands.asciidoc b/doc/Development/RepositoryCommands.asciidoc deleted file mode 100644 index 13e2f8e..0000000 --- a/doc/Development/RepositoryCommands.asciidoc +++ /dev/null @@ -1,6 +0,0 @@ -== Repository commands -[code, sh] ----- -# listing branches -curl --request GET --url https://neueland.iserlohn-fortress.net/gitea/api/v1/repos/aqua/smolbote/branches ----- diff --git a/doc/Development/Session.asciidoc b/doc/Development/Session.asciidoc deleted file mode 100644 index 846d6a3..0000000 --- a/doc/Development/Session.asciidoc +++ /dev/null @@ -1,19 +0,0 @@ -== Session - -== Session JSON structure -- windows: list of windows - -=== Window -- subwindows: list of subwindows - -=== Subwindow -- profile: profile ID -- tabs: list of views -- current: current tab index - -=== View -- profile: profile ID -- history: view history - -Storing history: compress, toBase64 (to make printable), toQString (to store in json) -Restoring history: toLatin1 (turn into bytearray), fromBase64, uncompress diff --git a/doc/Development/Translating.asciidoc b/doc/Development/Translating.asciidoc deleted file mode 100644 index f79fa56..0000000 --- a/doc/Development/Translating.asciidoc +++ /dev/null @@ -1,16 +0,0 @@ -== Translating -[code, sh] ----- -# generating translations -lupdate src/ lib/ -ts lang/.ts - -# updating translations -lupdate src/ lib/ -no-obsolete -ts lang/.ts - -# generate lang/.qm -lrelease lang/.ts ----- - -=== Using translations - --browser.locale # set Qt translation; ex. de - --browser.translation # set translation file; ex. /home/user/.config/smolbote/lang/custom-translate.qm diff --git a/doc/Development/Updater.asciidoc b/doc/Development/Updater.asciidoc deleted file mode 100644 index a039318..0000000 --- a/doc/Development/Updater.asciidoc +++ /dev/null @@ -1,25 +0,0 @@ -== Updater - -=== Creating manifest -[code, sh] ----- -find windows/ -type f | xargs sha512sum | sed 's/windows\///' > windows-sha512.txt -find windows/ -type d -exec chmod 755 {} + ----- - -=== Building - -You can build for the current system using: -[code, sh] ----- -go build -# remove debug information -strip updater ----- - -You can also cross-compile for other systems by setting GOOS and GOARCH. For a -list of supported platforms, use `go tool dist list`. -[code, sh] ----- -GOOS=windows GOARCH=amd64 go build ----- diff --git a/doc/Development/git.asciidoc b/doc/Development/git.asciidoc deleted file mode 100644 index e9e8b61..0000000 --- a/doc/Development/git.asciidoc +++ /dev/null @@ -1,10 +0,0 @@ -== git - -=== Updating submodules -[source, sh] ----- -git submodule update --remote --merge - -# add to commit -git add 3rd-party/ ----- diff --git a/doc/Usage.asciidoc b/doc/Usage.asciidoc deleted file mode 100644 index ee2cc20..0000000 --- a/doc/Usage.asciidoc +++ /dev/null @@ -1,21 +0,0 @@ -== Keyboard shortcuts -- F4 to focus the address bar and type an address; F2 show its menu -- Ctrl + Left/Right - go back/forward -- Ctrl + T - new tab -- Ctrl + X - close tab -- Ctrl + O/P - previous tab/next tab -- Ctrl + Shift + O/P - move tab left/right -- Ctrl + B - show/hide bookmarks -- Ctrl + D - show/hide downloads - -== Subwindows -A subwindow is a multiple document interface window that contains a collection -of tabs and has a default profile. It can be minimized, resized, moved, -maximized, tiled (F9) and cascaded (F10) within the main window. - -- Ctrl + G - new subwindow -- Ctrl + W - close subwindow - -include::Usage/Profile.asciidoc[] - -include::Usage/Configuration.asciidoc[] diff --git a/doc/Usage/CommandLine.asciidoc b/doc/Usage/CommandLine.asciidoc deleted file mode 100644 index 00a8d6c..0000000 --- a/doc/Usage/CommandLine.asciidoc +++ /dev/null @@ -1,14 +0,0 @@ -== Command-line Options - -=== General -* `-h`, `--help`: Display command-line options list.. -* `-v`, `--version`: Display version information. -* `--build`: Display build commit. - -=== Configuration -* `-c`, `--config`: Set configuration file. -* `--no-remote`: Don't check for other instances when starting. - -=== Sessions -* `-s, --session`: Open the selected session. -* `--pick-session`: Open all available sessions and select which one to open. diff --git a/doc/Usage/Configuration.asciidoc b/doc/Usage/Configuration.asciidoc deleted file mode 100644 index b1dbec5..0000000 --- a/doc/Usage/Configuration.asciidoc +++ /dev/null @@ -1,14 +0,0 @@ -== Configuration - -The Configuration is loaded from the path specified by `--config`, by default -_~/.config/smolbote/smolbote.cfg_. - -You can set the value of configuration options using its name in a key=value -pair, for example: -[source, ini] ----- -mainwindow.height=600 ----- -For a full list of options, check `--help`. - -You can overwrite options at runtime using the option name as a parameter. diff --git a/doc/Usage/Filter.asciidoc b/doc/Usage/Filter.asciidoc deleted file mode 100644 index d23d57a..0000000 --- a/doc/Usage/Filter.asciidoc +++ /dev/null @@ -1,12 +0,0 @@ -== Url Request Filter -smolbote has a singular URL request filter that is installed onto all profiles. -Any setting applied to it will be applied to all profiles. - -=== filter.header - A list of header-value pairs, separated by a colon (':'). - -You can specify multiple headers by using --filter.header multiple times: -[source, sh] ----- -poi --filter.header "Dnt:1" --filter.header "Accept:text/html" ----- diff --git a/doc/Usage/Linux.asciidoc b/doc/Usage/Linux.asciidoc deleted file mode 100644 index 748ea10..0000000 --- a/doc/Usage/Linux.asciidoc +++ /dev/null @@ -1,15 +0,0 @@ -== Linux - -=== firejail -To launch poi by default with firejail, symlink /usr/bin/firejail to the poi -executable: - -[source, sh] ----- -# poi is installed to /usr/local/bin/poi, and local/sbin is before local/bin. -ln -s /usr/bin/firejail /usr/local/sbin/poi ----- - -To add the poi.profile to firejail, copy or symlink it to '/etc/firejail' or -'~/.config/firejail'. - diff --git a/doc/Usage/Plugins.asciidoc b/doc/Usage/Plugins.asciidoc deleted file mode 100644 index 1f2d3a0..0000000 --- a/doc/Usage/Plugins.asciidoc +++ /dev/null @@ -1,7 +0,0 @@ -== Plugins -Plugins a way of extending smolbote's functionality using the Qt plugin system. -They are not to be confused with NPAPI/PPAPI or WebExtension plugins. - -To enable a plugin either copy it or symlink it in the plugins.path location, -or set its absolute path as the plugins.path. - diff --git a/doc/Usage/Profile.asciidoc b/doc/Usage/Profile.asciidoc deleted file mode 100644 index 79506fd..0000000 --- a/doc/Usage/Profile.asciidoc +++ /dev/null @@ -1,37 +0,0 @@ -== Profiles -A Profile is a collection of settings, policies, scripts, cookies, cache and -history. Profiles can be used to isolate pages from each other. - -Off-the-record profiles only use in-memory cache and save no files to disk. - -Profiles can be either temporary or permanent. Temporary profiles are expire -when the application is closed, whereas permanent profiles are kept between -runs. - -Each window has a default profile it uses when opening new tabs. This can be -changed from the window's menu. Additionally, tabs can have their profiles -individually changed from their context menu. - -Because profiles store all their data separately, you can log in into the same -site with a different account from each profile. However, links opened into new -tabs will still use the subwindow's default profile. For example, you can set a -profile to hold login information for a site, but all new tabs opened from that -site would still be using the default off-the-record profile. - -Profiles are read from profile.path - -Settings - -- otr (defaults to true) - is this profile off-the-record -- name (defaults to the configuration file name) -- search (defaults to profile.search) - search engine url -- homepage (defaults to profile.homepage) -- newtab (defaults to profile.newtab) - -Properties -Key is property name; value is property value - -Attributes -see QWebEngineSetting::WebAttribute for list of IDs. -Key is attribute id; value is attribute value (true/false) - diff --git a/doc/building.md b/doc/building.md new file mode 100644 index 0000000..9ea9344 --- /dev/null +++ b/doc/building.md @@ -0,0 +1,59 @@ +## Building from source + +### Dependencies +- [Qt](https://www.qt.io/) +- [meson](https://mesonbuild.com/) 0.52.0 or later +- [kconfiglib](https://github.com/ulfalizer/Kconfiglib/) +- A compiler with C++17 support +- spdlog: if not found can be downloaded by meson + +### Optional dependencies +- openssl or libressl: for signing plugins +- breakpad-client +- gtest + +### Steps +``` +# clone the repository +git clone https://neueland.iserlohn-fortress.net/gitea/aqua/smolbote.git smolbote.git +cd smolbote.git + +# Get the submodules +git submodule init +git submodule update + +# configure +mkdir build +meson build + +# make +ninja +``` + +## Using meson + +### Listing build options +``` +build% meson configure +``` + +### Changing build options +``` +build% meson configure -D= +``` + +### Prevent meson from downloading wraps +During configure, meson can download missing dependencies on its own using +wraps. To disable this, pass '--wrap-mode=nodownload' during the configure +phase: +``` +repo% meson --wrap-mode=nodownload build-path +``` + +For more information on how to use meson, see the meson [quick quide](https://mesonbuild.com/Quick-guide.html). + +## Configuring builds +smolbote uses Kconfig to store and customize features and default settings such +as keyboard shortcuts and paths. You can edit these settings using `menuconfig` +from kconfiglib or similar. + diff --git a/doc/contributing.md b/doc/contributing.md new file mode 100644 index 0000000..a5cd0ae --- /dev/null +++ b/doc/contributing.md @@ -0,0 +1,37 @@ +## Guidelines + +smolbote is written under the C++17 standard, without any compiler-specific +extensions. Source code should be kept as platform-agnostic as possible. + +## General +* All behaviour, where possible, should be configurable. +* Configuration option names should be as self-descriptive as possible. +* Use sane defaults: normally the program should "just work". + +## Qt +* Check pointers with `Q_CHECK_PTR`. +* Use the Qt5 signal/slot syntax (&Class::method) over the old string-based + syntax (SIGNAL/SLOT). This enables compile-time connect checks. +* Prefer QVector over QList: http://lists.qt-project.org/pipermail/development/2017-March/029040.html +* Use [clazy](https://github.com/KDE/clazy) to check Qt semantics. + +## Licensing +Smolbote is licensed under GPLv3 _only_, and explicitly does not use any +self-updating "-or-later" licensing. Your code needs to be compatible with it, +and have a license header in the style used by the project. + +Interfaces (located in include/) should be licensed under MIT. This is to allow +more license compatibility for plugins. + +### SPDX-License-Identifier +A full list of license identifiers can be found on [the SPDX website](https://spdx.org/licenses/). + +## Style +There is a clang-format style in .clang-format. + +## How to format patch for email +``` +git format-patch $from-commit..$to-commit +``` +Email patches to _aqua at iserlohn dash fortress dot net_. + diff --git a/doc/images/browser-for-fun.png b/doc/images/browser-for-fun.png deleted file mode 100644 index 72d24e6..0000000 Binary files a/doc/images/browser-for-fun.png and /dev/null differ diff --git a/doc/smolbote.asciidoc b/doc/smolbote.asciidoc deleted file mode 100644 index 101ce77..0000000 --- a/doc/smolbote.asciidoc +++ /dev/null @@ -1,22 +0,0 @@ -= smolbote: yet another no-frills web browser -:doctype: book -:toc: left -:data-uri: - -[preface] -image::browser-for-fun.png[World Domination cat, role="thumb right"] -smolbote is a cross-platform keep-it-simple free software web browser based on -Qt and QtWebEngine. - -''' - -include::Usage/CommandLine.asciidoc[] - -include::Usage/Configuration.asciidoc[] - -include::Usage/Profile.asciidoc[] - -include::Usage/Plugins.asciidoc[] - -include::Usage/Filter.asciidoc[] - -- cgit v1.2.1