diff --git a/.github/workflows/integration_tests.yml b/.github/workflows/integration_tests.yml new file mode 100644 index 000000000..1a2083870 --- /dev/null +++ b/.github/workflows/integration_tests.yml @@ -0,0 +1,23 @@ +name: Integration tests +on: + [push, pull_request] + +jobs: + integration-tests: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: Update the system + run: sudo apt update -y + + - name: Install dependencies + run: | + sudo apt install -y shunit2 podman + + - name: Integration tests + run: ./run_tests.sh --integration diff --git a/.github/workflows/kcov.yml b/.github/workflows/kcov.yml index 2b6b41fb8..5ca313ce8 100644 --- a/.github/workflows/kcov.yml +++ b/.github/workflows/kcov.yml @@ -10,7 +10,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: fetch-depth: 3 @@ -37,7 +37,7 @@ jobs: run: | kcov --include-path=src,kw \ --exclude-pattern=src/bash_autocomplete.sh,src/help.sh \ - kcov_out/ ./run_tests.sh + kcov_out/ ./run_tests.sh --unit - name: Upload coverage do codecov run: | diff --git a/.github/workflows/shellcheck_reviewdog.yml b/.github/workflows/shellcheck_reviewdog.yml index 528d2360a..6629e9f49 100644 --- a/.github/workflows/shellcheck_reviewdog.yml +++ b/.github/workflows/shellcheck_reviewdog.yml @@ -6,7 +6,7 @@ jobs: name: runner / shellcheck runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: shellcheck uses: reviewdog/action-shellcheck@v1 with: diff --git a/.github/workflows/shfmt.yml b/.github/workflows/shfmt.yml index 10dda5224..7022c28c3 100644 --- a/.github/workflows/shfmt.yml +++ b/.github/workflows/shfmt.yml @@ -5,7 +5,7 @@ jobs: sh-checker: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Run the sh-checker uses: luizm/action-sh-checker@v0.3.0 env: diff --git a/.github/workflows/test_setup_and_docs.yml b/.github/workflows/test_setup_and_docs.yml index c4ed379d4..7ae18f206 100644 --- a/.github/workflows/test_setup_and_docs.yml +++ b/.github/workflows/test_setup_and_docs.yml @@ -10,7 +10,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v3 + uses: actions/checkout@v4 # This is here just because git-email cannot be installed in the # Github CI otherwise. diff --git a/.github/workflows/unit_tests.yml b/.github/workflows/unit_tests.yml index b5620689b..c9dc41266 100644 --- a/.github/workflows/unit_tests.yml +++ b/.github/workflows/unit_tests.yml @@ -10,7 +10,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: fetch-depth: 3 @@ -30,4 +30,4 @@ jobs: - name: Unit tests run: | - ./run_tests.sh + ./run_tests.sh --unit diff --git a/Dockerfile b/Dockerfile index 48309ec59..041a6bc0b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -21,5 +21,6 @@ RUN wget https://github.com/koalaman/shellcheck/releases/download/v0.10.0/shellc && cp shellcheck-v0.10.0/shellcheck /usr/bin/ \ && rm -rf shellcheck-v0.10.0 -RUN apt install -y shunit2 bc sqlite3 bsdmainutils libxml-xpath-perl +RUN apt install -y shunit2 bc sqlite3 bsdmainutils libxml-xpath-perl software-properties-common python3-launchpadlib \ + python3-venv python3-pip #USER kworkflow diff --git a/Jenkinsfile b/Jenkinsfile new file mode 100644 index 000000000..9a7827fc8 --- /dev/null +++ b/Jenkinsfile @@ -0,0 +1,24 @@ +pipeline { + agent any + stages { + + stage('Build'){ + steps{ + sh ''' + apt update -y + apt install -y kcov shunit2 bc sqlite3 bsdmainutils libxml-xpath-perl + ./run_tests.sh prepare + mkdir kcov_out/ + git config --global user.email "kw@kworkflow.net" + git config --global user.name "Kworkflow" + ./run_tests.sh + kcov --include-path=src,kw \ + --exclude-pattern=src/bash_autocomplete.sh,src/help.sh \ + kcov_out/ ./run_tests.sh + ''' + cobertura autoUpdateHealth: false, autoUpdateStability: false, coberturaReportFile: 'kcov_out/', conditionalCoverageTargets: '70, 0, 0', failUnhealthy: false, failUnstable: false, lineCoverageTargets: '80, 0, 0', maxNumberOfBuilds: 0, methodCoverageTargets: '80, 0, 0', onlyStable: false, sourceEncoding: 'ASCII', zoomCoverageChart: false + } + } + + } +} diff --git a/database/migrate_legacy_data_20220101.sh b/database/migrate_legacy_data_20220101.sh index 906db1709..3082fe063 100755 --- a/database/migrate_legacy_data_20220101.sh +++ b/database/migrate_legacy_data_20220101.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # This file handles the migration of legacy user data, from the old directories and files # storage, to the new database model @@ -99,7 +99,7 @@ function migrate_statistics() cmd_manager 'SILENT' "mv ${datadir}/statistics ${datadir}/legacy_statistics" if [[ "$?" != 0 ]]; then complain "Couldn't rename ${datadir}/statistics ${datadir}/legacy_statistics" - return 1 #EPERM + return 1 # EPERM fi } @@ -161,7 +161,7 @@ function migrate_pomodoro() cmd_manager 'SILENT' "mv ${datadir}/pomodoro ${datadir}/legacy_pomodoro" if [[ "$?" != 0 ]]; then complain "Couldn't rename ${datadir}/pomodoro ${datadir}/legacy_pomodoro" - return 1 #EPERM + return 1 # EPERM fi } @@ -216,20 +216,20 @@ function migrate_kernel_configs() cmd_manager 'SILENT' "cp -r ${configs_dir}/. ${datadir}/configs" if [[ "$?" != 0 ]]; then complain "Couldn't copy kernel config files from ${configs_dir} to ${datadir}/configs" - return 1 #EPERM + return 1 # EPERM fi # mark migrated directories to avoid duplicated data cmd_manager 'SILENT' "mv ${datadir}/configs/configs ${datadir}/configs/legacy_configs" if [[ "$?" != 0 ]]; then complain "Couldn't rename ${datadir}/configs/configs to ${datadir}/configs/legacy_configs" - return 1 #EPERM + return 1 # EPERM fi cmd_manager 'SILENT' "mv ${datadir}/configs/metadata ${datadir}/configs/legacy_metadata" if [[ "$?" != 0 ]]; then complain "Couldn't rename ${datadir}/configs/metadata to ${datadir}/configs/legacy_metadata" - return 1 #EPERM + return 1 # EPERM fi } diff --git a/documentation/conf.py b/documentation/conf.py index 6d9251d5f..54d51ed9d 100644 --- a/documentation/conf.py +++ b/documentation/conf.py @@ -172,15 +172,15 @@ ('man/features/kw-drm', 'kw-drm', 'drm subsystem support', [author], 1), ('man/features/kw-explore', 'kw-explore', 'git grep wrapper', [author], 1), ('man/features/kw-init', 'kw-init', 'initialize kworkflow.config', [author], 1), - ('man/features/kw-mail', 'kw-mail', 'git send-email wrapper', ['Rubens Gomes Neto'], 1), + ('man/features/kw-send-patch', 'kw-send-patch', 'git send-email wrapper', ['Rubens Gomes Neto'], 1), ('man/features/kw-maintainers', 'kw-maintainers', 'display module maintainers', [author], 1), ('man/features/kw-pomodoro', 'kw-pomodoro', 'pomodoro style time management', [author], 1), ('man/features/kw-report', 'kw-report', 'user data report support', [author], 1), ('man/features/kw-ssh', 'kw-ssh', 'ssh access', [author], 1), - ('man/features/kw-vars', 'kw-vars', 'view kw config values', [author], 1), ('man/features/kw-vm', 'kw-vm', 'commands to work with QEMU VMs', [author], 1), ('man/features/kw-self-update', 'kw-self-update', 'kw self-update mechanism', ['David Tadokoro, Everaldo Junior'], 1), ('man/features/kw-patch-hub', 'kw-patch-hub', 'UI with lore.kernel.org archives', ['David Tadokoro, Rodrigo Siqueira'], 1), + ('man/features/kw-bd', 'kw-bd', 'build and then deploy the kernel', ['Briza Mel de Sousa, Lorenzo Salvador'], 1), ] diff --git a/documentation/content/codingstyle.rst b/documentation/content/codingstyle.rst index a63180791..b6257d237 100644 --- a/documentation/content/codingstyle.rst +++ b/documentation/content/codingstyle.rst @@ -244,11 +244,11 @@ a developer. We also encourage using the ``assert_equals_helper`` helper function, which provides a wrapper capable of spitting a useful error message in case the assertion fails. Ideally, one should do either:: - assert_equals_helper "$error_message" "($LINENO)" "$output" "$expected_output" + assert_equals_helper "$error_message" "($LINENO)" "$expected_output" "$output" or:: - assertEquals "($LINENO)" "$output" "$expected_output" + assertEquals "($LINENO)" "$expected_output" "$output" Help functions -------------- @@ -280,6 +280,18 @@ it stays consistent across multiple platforms. If you need to add extra lines while generating a string you can use the ``$'\n'`` literal to add a new line character or other special characters. +Single quotes instead double quotes +----------------------------------- + +Whenever you have a variable that stands for a string that doesn’t contain +shell expansions, use single quotes instead of double quotes. For example:: + + var='literal-value' #Single quotes + +or:: + + path="${HOME}/path/to/file" #Double quotes + String concatenation -------------------- @@ -317,6 +329,12 @@ Good:: rsync --verbose --recursive dir1 dir2 +Declaring shebangs +------------------ + +Avoid using "#!/bin/bash" when writing new bash files. This usual shebang may not work for +some linux distributions that don't follow FHS, such as NixOS. Use "#!/usr/bin/env bash" instead. + Conclusion ---------- diff --git a/documentation/content/project_structure.rst b/documentation/content/project_structure.rst index 53bcf953c..197aa1f52 100644 --- a/documentation/content/project_structure.rst +++ b/documentation/content/project_structure.rst @@ -44,7 +44,7 @@ Components We treat every feature under kw as a specific component, usually with a dedicated file. For example, the deploy feature implementation can be seen in -the `src/deploy.sh` file and the mail implementation in the `src/mail.sh` file. +the `src/deploy.sh` file and the mail implementation in the `src/send_patch.sh` file. Usually, the component file follows this basic structure (see :ref:`code-style ` for more details): diff --git a/documentation/content/tests.rst b/documentation/content/tests.rst index fac0bc334..08a81bfd5 100644 --- a/documentation/content/tests.rst +++ b/documentation/content/tests.rst @@ -1,5 +1,5 @@ =============== - About Tests +About Tests =============== .. _tests: @@ -9,6 +9,12 @@ Kw's tests rely on `shunit2`. The `run_tests.sh` script automatically detects can have shunit2 source code in `tests/` (you can clone it from https://github.com/kward/shunit2). +In order to run the integration tests, it is necessary to install Podman and to +configure it to run in rootless mode as explained in the official documentation: +https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md. +Podman is available via the default package manager of popular distros, such as +Arch, Debian, Fedora and those based on them. + If you want to run all the tests, try:: ./run_tests.sh @@ -19,7 +25,43 @@ List all available test files:: Or run individual tests with:: - ./run_tests.sh test TESTFILE1 ... + ./run_tests.sh test TEST_FILE_1 ... + +To limit the scope of the tests, pass the flag `--unit` or `--integration` as +the first argument to any of the examples above. So, the syntax is:: + + ./run_tests.sh [scope] [command] [args] + +Where `[scope]` can be `--unit` or `--integration`. The placeholder `[command]` +can be either `list`, `test` or simply omitted in order to run all tests. Here +are some examples: + +.. code-block:: bash + + ./run_tests.sh --unit # run all unit tests + ./run_tests.sh --unit list # list all unit tests + ./run_tests.sh --unit test device # test device unit test + ./run_tests.sh --unit clear-cache # clear unit tests cache + ./run_tests.sh --integration # run all integration tests + ./run_tests.sh --integration list # list all integration tests + ./run_tests.sh --integration test device # test device integration test + ./run_tests.sh --integration clear-cache # clear integration tests cache + ./run_tests.sh # run all tests + ./run_tests.sh list # list all tests + ./run_tests.sh test device # run all device tests + ./run_tests.sh clear-cache # clear all cache + +The integration tests can take over 10 minutes to run in the first time because +podman is building the container images to be used in the tests, which requires +installing kw's dependencies in the supported distros. After the images have +been built and cached, running the integration tests should take only a few +seconds each time. + +Then, the local kw repo is copied to the containers and installed again, which +takes very few seconds. For optimization purposes, the containers are reused +across tests. If you add a new commit or checkout to another branch, such that +HEAD points to another commit, the containers will be destroyed and created +again in order to install the current local version of kw. Kw is already prepared to run tests, build the documentation and check the installation in the github workflow. diff --git a/documentation/dependencies/arch.dependencies b/documentation/dependencies/arch.dependencies index e66eed2fb..efc867963 100644 --- a/documentation/dependencies/arch.dependencies +++ b/documentation/dependencies/arch.dependencies @@ -26,3 +26,6 @@ curl perl-xml-xpath coreutils b4 +procps-ng +pciutils +libnotify diff --git a/documentation/dependencies/debian.dependencies b/documentation/dependencies/debian.dependencies index dd3906cbe..aa007671f 100644 --- a/documentation/dependencies/debian.dependencies +++ b/documentation/dependencies/debian.dependencies @@ -28,3 +28,6 @@ curl libxml-xpath-perl coreutils b4 +procps +pciutils +libnotify-bin diff --git a/documentation/dependencies/fedora.dependencies b/documentation/dependencies/fedora.dependencies index 71becf38d..770a68e84 100644 --- a/documentation/dependencies/fedora.dependencies +++ b/documentation/dependencies/fedora.dependencies @@ -24,3 +24,6 @@ curl perl-XML-XPath coreutils b4 +procps-ng +pciutils +libnotify diff --git a/documentation/dependencies/kernel_build/arch.dependencies b/documentation/dependencies/kernel_build/arch.dependencies new file mode 100644 index 000000000..9bbd5ff01 --- /dev/null +++ b/documentation/dependencies/kernel_build/arch.dependencies @@ -0,0 +1,17 @@ +make +base-devel +linux-headers +bison +flex +openssl +ncurses +pahole +xmlto +kmod +inetutils +bc +libelf +cpio +perl +tar +xz diff --git a/documentation/dependencies/kernel_build/debian.dependencies b/documentation/dependencies/kernel_build/debian.dependencies new file mode 100644 index 000000000..5389331a8 --- /dev/null +++ b/documentation/dependencies/kernel_build/debian.dependencies @@ -0,0 +1,20 @@ +libncurses-dev +gawk +flex +bison +openssl +libssl-dev +dkms +libelf-dev +libudev-dev +libpci-dev +libiberty-dev +autoconf +llvm +exuberant-ctags +build-essential +xmlto +kmod +dwarves +clang +lld diff --git a/documentation/dependencies/kernel_build/fedora.dependencies b/documentation/dependencies/kernel_build/fedora.dependencies new file mode 100644 index 000000000..4b93e530d --- /dev/null +++ b/documentation/dependencies/kernel_build/fedora.dependencies @@ -0,0 +1,12 @@ +qt3-devel +libXi-devel +diffutils +gcc-c++ +ncurses-devel +bison +flex +openssl-devel +elfutils-libelf-devel +openssl +dwarves +llvm diff --git a/documentation/man/features/kw-backup.rst b/documentation/man/features/kw-backup.rst index 35f6a756e..69f1c484d 100644 --- a/documentation/man/features/kw-backup.rst +++ b/documentation/man/features/kw-backup.rst @@ -1,6 +1,6 @@ -========= -kw-backup -========= +============================================= +kw-backup - Save and restore kw internal data +============================================= .. _backup-doc: @@ -45,4 +45,4 @@ save it into /documents/backup, then run:: To restore a backup, use the `\--restore` option. Suppose you want to restore the backup stored in /documents/backup/kw-backup-from-yesterday.tar.gz, run:: - kw backup --restore /documents/backup/kw-backup-from-yesterday.tar.gz \ No newline at end of file + kw backup --restore /documents/backup/kw-backup-from-yesterday.tar.gz diff --git a/documentation/man/features/kw-bd.rst b/documentation/man/features/kw-bd.rst new file mode 100644 index 000000000..179755c52 --- /dev/null +++ b/documentation/man/features/kw-bd.rst @@ -0,0 +1,35 @@ +====================================== +kw-bd - Build the kernel and deploy it +====================================== + +.. _bd-doc: + +SYNOPSIS +======== + +*kw* (*bd*) + +DESCRIPTION +=========== + +Kw bd is expected to run inside a kernel tree. It executes the build, and if +there are no errors, it proceeds with deploying the new kernel. + +Currently, all arguments invoked along with kw bd will be redirected to kw +deploy. + +See the kw build and kw deploy man pages for more information. + +.. note:: + This command must be run inside of a kernel tree. + +EXAMPLES +======== + +For simply executing build and deploy use:: + + kw bd + +If you want to build and deploy the kernel with --create-package option use:: + + kw bd --create-package diff --git a/documentation/man/features/kw-build.rst b/documentation/man/features/kw-build.rst index 0a8af5129..085c1e514 100644 --- a/documentation/man/features/kw-build.rst +++ b/documentation/man/features/kw-build.rst @@ -1,6 +1,6 @@ -======== -kw-build -======== +======================= +kw-build - Build kernel +======================= .. _build-doc: @@ -17,6 +17,7 @@ SYNOPSIS | *kw* (*b* | *build*) [(-c | \--clean)] [\--alert=(s | v | (sv | vs) | n)] | *kw* (*b* | *build*) [(-f | \--full-cleanup)] [\--alert=(s | v | (sv | vs) | n)] | *kw* (*b* | *build*) [\--cflags] +| *kw* (*b* | *build*) [\--from-sha ] | *kw* (*b* | *build*) [\--verbose] DESCRIPTION @@ -40,7 +41,7 @@ OPTIONS -n, \--menu: The menu option invokes the kernel menuconfig. Notice that the default menu - config can be changed in the **kworkflow.config** file by setting a different + config can be changed in the **build.config** file by setting a different option in *menu_config*. If the user is working in a *cross-compile* environment, it is recommended to use this option to avoid messing with the config file manually. @@ -48,7 +49,7 @@ OPTIONS -d, \--doc: The doc option provides a mechanism for building the kernel-doc; by default, it will build htmldocs. Users can change the default documentation output by - changing the parameter *doc_type* in the **kworkflow.config** file. + changing the parameter *doc_type* in the **build.config** file. -S, \--cpu-scaling: The cpu-scaling option lets the user set whichever CPU usage they want from @@ -61,12 +62,12 @@ OPTIONS -w, \--warnings (1 | 2 | 3 | 12 | 13 | 23 | 123): This can be used to enable compilation warnings accordingly. You can set the - default log level via `build.config` file under the option `warning_level`. + default log level via **build.config** file under the option `warning_level`. Please check the kernel's ``make help`` for more info. --s, \--save-log-to=path: +-s, \--save-log-to path: This option will save the full compilation log with the enabled warnings to - the specified path. You can set the default log path in the `build.config` + the specified path. You can set the default log path in the **build.config** file via `log_path` option. \--llvm: @@ -102,10 +103,15 @@ OPTIONS | **sv** or **vs** enables both. | **n** (or any other option) disables notifications (this is the default). +\--from-sha: + Build every commit after to branch head. Useful for testing if all patches in + patchset compile. + EXAMPLES ======== -For these examples, we suppose the fields in your **kworkflow.config** file are -already configured. +For these examples, we assume that the relevant fields in your configuration +files (located by default in **.kw/**) have already been setup. We recommend +the use of ``kw config`` for managing your local and global configurations. For building and installing a new module version based on the current kernel version, you can use:: @@ -141,7 +147,7 @@ using:: Sometimes we have a lot of error message that does not fit in the terminal buffer; in these cases it is helpful to save all logs in a file:: - kw b --warnings 123 --save-log-to=ALL_WARNINGS.log + kw b --warnings 123 --save-log-to ALL_WARNINGS.log If you want to use llvm:: @@ -157,4 +163,12 @@ If you want to reset the kernel tree to its default, `all config and script outp If you want to use cflags:: - kw b --cflags "-O3 -pipe -march=native" \ No newline at end of file + kw b --cflags "-O3 -pipe -march=native" + +If you want to build every commit after HEAD~2 to HEAD:: + + kw b --from-sha HEAD~2 + +If you want to build every commit after ee3b5 to HEAD:: + + kw b --from-sha ee3b5 diff --git a/documentation/man/features/kw-codestyle.rst b/documentation/man/features/kw-codestyle.rst index 29c9587e1..c6b9cd985 100644 --- a/documentation/man/features/kw-codestyle.rst +++ b/documentation/man/features/kw-codestyle.rst @@ -1,12 +1,14 @@ -============ -kw-codestyle -============ +================================= +kw-codestyle - Checkpatch wrapper +================================= .. _codestyle-doc: SYNOPSIS ======== -*kw* (*c* | *codestyle*) [ | | ] +| *kw* (*c* | *codestyle*) +| *kw* (*c* | *codestyle*) [ | | ] +| *kw* (*c* | *codestyle*) [\--verbose] [ | | ] DESCRIPTION =========== @@ -22,10 +24,14 @@ OPTIONS Define which files to run checkpatch on. Defaults to current working directory if it is a kernel tree. +\--verbose: + Display commands executed under the hood. + EXAMPLES ======== -For these examples, we suppose the fields in your **kworkflow.config** file are -already configured. +For these examples, we assume that the relevant fields in your configuration +files (located by default in **.kw/**) have already been setup. We recommend +the use of ``kw config`` for managing your local and global configurations. For checking the code style:: diff --git a/documentation/man/features/kw-config.rst b/documentation/man/features/kw-config.rst index 0e9842222..48a4d1878 100644 --- a/documentation/man/features/kw-config.rst +++ b/documentation/man/features/kw-config.rst @@ -1,6 +1,6 @@ -========= -kw-config -========= +========================================= +kw-config - Manage kw configuration files +========================================= .. _config-doc: diff --git a/documentation/man/features/kw-debug.rst b/documentation/man/features/kw-debug.rst index 9e1700ce3..d485692ed 100644 --- a/documentation/man/features/kw-debug.rst +++ b/documentation/man/features/kw-debug.rst @@ -1,6 +1,6 @@ -======== -kw-debug -======== +======================= +kw-debug - Kernel debug +======================= .. _debug-doc: @@ -12,6 +12,7 @@ SYNOPSIS | *kw* *debug* [(-l | \--list)[=( | )]] [(-e | \--event)] | *kw* *debug* [\--reset] | *kw* *debug* [(-h | \--help)] +| *kw* *debug* [(\--verbose)] DESCRIPTION =========== @@ -123,6 +124,11 @@ OPTIONS `\--dmesg`, kw will (1) clean the dmesg log, (2) run the command, (3) and collect the log. +\--verbose: + Verbose mode is an option that causes the kw program to display debug + messages to track its steps. This functionality is very useful during the + debugging process, allowing you to identify possible errors more easily. + EXAMPLES ======== diff --git a/documentation/man/features/kw-deploy.rst b/documentation/man/features/kw-deploy.rst index 130dae224..f91180a78 100644 --- a/documentation/man/features/kw-deploy.rst +++ b/documentation/man/features/kw-deploy.rst @@ -1,6 +1,6 @@ -========= -kw-deploy -========= +========================= +kw-deploy - Deploy kernel +========================= .. _deploy-doc: @@ -31,22 +31,23 @@ executed: You can specify the deploy target via command line by using the flag ``--remote :`` (e.g., ``--remote 172.16.254.1:22``); however, if -you do this frequently you will probably prefer to add this information to your -local **kworkflow.config**. See the example below:: +you plan on deploying to the same remote frequently can benefit from using the +``kw remote`` feature to save the SSH information in a configuration file +used by kw, for example:: - default_deploy_target=remote - ssh_user=root - ssh_ip=172.16.254.1 - ssh_port=22 + kw remote --add origin root@172.16.254.1 + +For more information, check ``kw remote --help`` If you want to install a new kernel version in your host machine, you can use the flag ``--local``; you will need to use your root password. -Another typical operation when deploying a new kernel to a test machine, it is -the reboot after the update. You can explicitly say it for **kw** by adding the -flag ``--reboot``, add this to the **kworkflow.config** with:: +Another typical operation when deploying a new kernel to a test machine is +rebooting after the update. You can add the ``--reboot`` flag to a command to +explicitly make **kw** reboot the machine afterwards, or you can set this to +always happen by modifying ``reboot_after_deploy`` flag in **deploy.config** with:: - reboot_after_deploy=yes + kw config deploy.reboot_after_deploy yes This can be used with conjunction the :ref:`build` command by invoking ``kw bd``. @@ -84,9 +85,10 @@ OPTIONS -s, \--ls-line: List available kernels separated by comma. --u [,...], \--uninstall [,...]: +-u ( | regex:)[,...], \--uninstall ( | regex:)[,...]: Remove a single kernel or multiple kernels; for removing - multiple kernels it is necessary to separate them with comma. + multiple kernels it is necessary to separate them with comma. A regex pattern + can also be passed as input, prefixed with 'regex:'. -f, \--force: Remove kernels even if they were not installed by kw (only valid with @@ -117,8 +119,9 @@ OPTIONS EXAMPLES ======== -For these examples, we suppose the fields in your **kworkflow.config** file are -already configured. +For these examples, we assume that the relevant fields in your configuration +files (located by default in **.kw/**) have already been setup. We recommend +the use of ``kw config`` for managing your local and global configurations. First, if you are working in a specific kernel module, and if you want to install your recent changes in your local machine you can use:: @@ -151,3 +154,17 @@ any other kw user. If you want to install a custom kernel from this package, you can use:: kw deploy --from-package 5.19.0-THIS-IS-AN-EXAMPLE+.kw.tar + +Below are examples of how to use `kw deploy --uninstall`: + +1) Full kernel name argument + + kw deploy --uninstall 'kernel1' + +2) Regular expression argument + + kw deploy --uninstall 'regex:kernel.*' + +3) Comma-separated list of full kernel names and regular expressions + + kw deploy --uninstall 'regex:kernel[1-3],kernel4,regex:kernel[5-6]' diff --git a/documentation/man/features/kw-device.rst b/documentation/man/features/kw-device.rst index 63114c1d4..26e1d25e1 100644 --- a/documentation/man/features/kw-device.rst +++ b/documentation/man/features/kw-device.rst @@ -1,6 +1,6 @@ -========= -kw-device -========= +========================================= +kw-device - Retrieve hardware information +========================================= .. _device-doc: diff --git a/documentation/man/features/kw-diff.rst b/documentation/man/features/kw-diff.rst index 505771e7e..688bfed9e 100644 --- a/documentation/man/features/kw-diff.rst +++ b/documentation/man/features/kw-diff.rst @@ -1,6 +1,6 @@ -======= -kw-diff -======= +=================== +kw-diff - Diff tool +=================== .. _diff-doc: @@ -22,4 +22,4 @@ OPTIONS \--verbose: Verbose mode is an option that causes the kw program to display debug messages to track its progress. This functionality is very useful during the debugging process, allowing - you to identify possible errors more easily. \ No newline at end of file + you to identify possible errors more easily. diff --git a/documentation/man/features/kw-drm.rst b/documentation/man/features/kw-drm.rst index bca5e6655..5a46e088c 100644 --- a/documentation/man/features/kw-drm.rst +++ b/documentation/man/features/kw-drm.rst @@ -1,6 +1,6 @@ -====== -kw-drm -====== +============================ +kw-drm - DRM subsystem tools +============================ .. _drm-doc: @@ -26,11 +26,11 @@ OPTIONS \--local, \--remote [:]: This option specifies the target device for the drm action, it can be a remote or local machine. If these options are not explicitly passed via - command line, **kw** going to take the target set in the variable - *default_deploy_target* (**kworkflow.config**) for identifying the target. + command line, **kw** is going to take the target set in the variable + *default_deploy_target* (**deploy.config**) for identifying the target. It is important to highlight that the drm feature **does not support VM**. --lm, \--load-module=[:,...][;:...]: +\--load-module=[:,...][;:...]: Allow user to specify one or more modules to be load with or without parameters. If you want to indicate more than one module, you have to separate them using ';'. Additionally, if users wish to provide specific @@ -39,7 +39,7 @@ OPTIONS will make sure that the target module will be load first and after that trigger the GUI. --um=[;;...], \--unload-module=[;;...]: +\--unload-module=[;;...]: This option allows users to unload one or more DRM drivers. Users can provide a single module to be unloaded or a list separated by ';'. This command first disables the user interface and, after that, unloads the module. @@ -55,8 +55,25 @@ OPTIONS systemctl operation but users can change this behavior by set *gui_off* with a specific command in the **kworkflow.config** file with the specific command. +\--gui-on-after-reboot: + This option sets the GUI to turn on automatically after the next reboot. By default, + it uses systemctl operation; however, users are free to add any specific + command for activating their preferred GUI in the variable *gui_on_after_reboot* + in the **kworkflow.config** file. + Note: This change will take effect only after the system is rebooted. To enable + the GUI immediately, use the --gui-on option. + +\--gui-off-after-reboot: + This option sets the GUI to turn off automatically after the next reboot. By default, + it uses systemctl operation; however, users are free to add any specific + command for deactivating their GUI in the variable *gui_off_after_reboot* + in the **kworkflow.config** file. + Note: This change will take effect only after the system is rebooted. To disable + the GUI immediately, use the --gui-off option. + \--conn-available: - Show all connectors available in the target machine. + Show all connectors available in the target machine. The ones marked with '*' + are enabled. \--modes: Show all available modes per card. @@ -68,8 +85,9 @@ OPTIONS EXAMPLES ======== -For these examples, we suppose the fields in your **kworkflow.config** file are -already configured. +For these examples, we assume that the relevant fields in your configuration +files (located by default in **.kw/**) have already been setup. We recommend +the use of ``kw config`` for managing your local and global configurations. If you are working with DRM drivers, you can take advantage of load and unload commands combined with GUI control commands. For example:: diff --git a/documentation/man/features/kw-env.rst b/documentation/man/features/kw-env.rst index f67cbf78a..8ec4b4574 100644 --- a/documentation/man/features/kw-env.rst +++ b/documentation/man/features/kw-env.rst @@ -1,6 +1,6 @@ -====== -kw-env -====== +=============================== +kw-env - kw environment manager +=============================== .. _env-doc: diff --git a/documentation/man/features/kw-explore.rst b/documentation/man/features/kw-explore.rst index 965fc1006..0f5a28aa6 100644 --- a/documentation/man/features/kw-explore.rst +++ b/documentation/man/features/kw-explore.rst @@ -1,13 +1,13 @@ -========== -kw-explore -========== +=========================== +kw-explore - Explore folder +=========================== .. _explore-doc: SYNOPSIS ======== *kw* (*e* | *explore*) [(-l | \--log) | (-g | \--grep) | (-a | \--all) | \--verbose] - [(-c | \--only-source) | (-H | \--only-header)] + [(-c | \--only-source) | (-H | \--only-header)] [(-C[] | \--show-context[=])] [-p] [ | ] DESCRIPTION @@ -45,5 +45,23 @@ OPTIONS -H | \--only-header: With this option, it is possible to show only the results from the header. +-C[] | \--show-context[=]: + Show lines of additional context above and below the matched line. + If is not specified, the default value of 3 will be used. + \--verbose: Verbose mode allows the user to see the commands executed under the hood. + +EXAMPLES +======== +To show matched line with context using long-form flag:: + + kw explore --show-context=5 search_string + +To show matched line with context using short flag:: + + kw explore -C5 search_string + +Search through all tracked and untracked files, default value of 3 will be used for context:: + + kw explore -C --all search_string diff --git a/documentation/man/features/kw-init.rst b/documentation/man/features/kw-init.rst index 394b5fb26..4b6770133 100644 --- a/documentation/man/features/kw-init.rst +++ b/documentation/man/features/kw-init.rst @@ -1,6 +1,6 @@ -======= -kw-init -======= +====================================== +kw-init - Create kw basic config files +====================================== .. _init-doc: @@ -11,9 +11,9 @@ SYNOPSIS DESCRIPTION =========== -This command creates a **.kw** folder containing a **kworkflow.config** file in +This command creates a **.kw** folder containing default configuration files in the current kernel directory. The primary reason for running ``kw init`` is to -pick up a freshly created config file. +pick up freshly created config files. OPTIONS ======= @@ -25,7 +25,7 @@ OPTIONS creating the local config file. \--arch : - Set the variable `arch` from the newly created **kworkflow.config** file. + Set the variable `arch` from the newly created **build.config** file. Before actually changing it, this option checks if ** is a valid architecture found in the **arch** folder from the kernel directory. @@ -34,7 +34,7 @@ OPTIONS and **, respectively. \--target : - Set the variable `default_deploy_target` from **kworkflow.config** to + Set the variable `default_deploy_target` from **deploy.config** to **, which can be local or remote. \--verbose: @@ -45,17 +45,19 @@ EXAMPLES For these examples, we suppose that the kernel directory is your current directory. -For initializing a **kworkflow.config** with `arch` set to arm, use:: +For initializing a **build.config** with `arch` set to arm, use:: kw init --arch arm -To initialize **kworkflow.config** with `arch` set to x86, `ssh_user` set to -john, `ssh_ip` set to localhost, and `ssh_port` set to 2222, run:: +To initialize **build.config** with `arch` set to x86 and a **kworkflow.config** +with `ssh_user` set to john, `ssh_ip` set to localhost, and `ssh_port` +set to 2222, run:: kw init --arch x86 --remote john@localhost:2222 -For initializing a **kworkflow.config** with `arch` set to arm64, `target` set to -remote, `ssh_user` mary, `ssh_ip` localhost, and `ssh_port` 1234, run:: +For initializing a **build.config** with `arch` set to arm64, a **deploy.config** +with `target` set to remote and a **kworkflow.config** with `ssh_user` mary, +`ssh_ip` localhost, and `ssh_port` 1234, run:: kw init --arch arm64 --remote mary@localhost:1234 --target remote diff --git a/documentation/man/features/kw-kernel-config-manager.rst b/documentation/man/features/kw-kernel-config-manager.rst index 21780f458..404da4e75 100644 --- a/documentation/man/features/kw-kernel-config-manager.rst +++ b/documentation/man/features/kw-kernel-config-manager.rst @@ -1,6 +1,6 @@ -======================== -kw-kernel-config-manager -======================== +===================================================== +kw-kernel-config-manager - Kernel config file manager +===================================================== .. _kernel-config-manager-doc: @@ -62,8 +62,9 @@ OPTIONS EXAMPLES ======== -In the following examples, we assume your **kworkflow.config** file is already -properly configured. +For these examples, we assume that the relevant fields in your configuration +files (located by default in **.kw/**) have already been setup. We recommend +the use of ``kw config`` for managing your local and global configurations. In case you want **kw** to save your current **.config** file, you can use:: diff --git a/documentation/man/features/kw-maintainers.rst b/documentation/man/features/kw-maintainers.rst index 5686b431d..59017a86e 100644 --- a/documentation/man/features/kw-maintainers.rst +++ b/documentation/man/features/kw-maintainers.rst @@ -1,6 +1,6 @@ -============== -kw-maintainers -============== +=========================================== +kw-maintainers - Display module maintainers +=========================================== .. _maintainers-doc: @@ -36,8 +36,9 @@ OPTIONS EXAMPLES ======== -For these examples, we suppose the fields in your **kworkflow.config** file are -already configured. +For these examples, we assume that the relevant fields in your configuration +files (located by default in **.kw/**) have already been setup. We recommend +the use of ``kw config`` for managing your local and global configurations. If you want to check the maintainers:: diff --git a/documentation/man/features/kw-patch-hub.rst b/documentation/man/features/kw-patch-hub.rst index f2c59916a..f70f5b474 100644 --- a/documentation/man/features/kw-patch-hub.rst +++ b/documentation/man/features/kw-patch-hub.rst @@ -1,6 +1,6 @@ -====================== -kw-patch-hub -====================== +=============================================== +kw-patch-hub - UI with lore.kernel.org archives +=============================================== .. _patch-hub-doc: diff --git a/documentation/man/features/kw-pomodoro.rst b/documentation/man/features/kw-pomodoro.rst index 3e330687a..e534274e4 100644 --- a/documentation/man/features/kw-pomodoro.rst +++ b/documentation/man/features/kw-pomodoro.rst @@ -1,6 +1,6 @@ -=========== -kw-pomodoro -=========== +=============================================== +kw-pomodoro - Create and manage Pomodoro timers +=============================================== .. _pomodoro-doc: @@ -9,6 +9,7 @@ SYNOPSIS | *kw* (*p* | *pomodoro*) (-t | \--set-timer)