pax_global_header00006660000000000000000000000064151325553410014516gustar00rootroot0000000000000052 comment=2d8a04bb29533d161fa5661578c78ce0569661b7 kworkflow-0.10/000077500000000000000000000000001513255534100134635ustar00rootroot00000000000000kworkflow-0.10/.github/000077500000000000000000000000001513255534100150235ustar00rootroot00000000000000kworkflow-0.10/.github/ISSUE_TEMPLATE/000077500000000000000000000000001513255534100172065ustar00rootroot00000000000000kworkflow-0.10/.github/ISSUE_TEMPLATE/bug_report.md000066400000000000000000000012441513255534100217010ustar00rootroot00000000000000--- name: Bug report about: Create a report to help us improve title: '' labels: 'bug' assignees: '' --- **Description:** [Add a clear and concise description of what the bug is.] **How to Reproduce:** [Steps to reproduce the behavior: 1. Which commands were invoked 2. Where the error appears] **Expected behavior:** [A clear and concise description of what you expected to happen.] **Screenshots:** [If applicable, add screenshots to help explain your problem.] **System information:** - OS: [e.g. Debian Bullseye] - kw Version: [use `kw version`] - Bash Version [use `bash --version`] **Additional context:** [Add any other context about the problem here.] kworkflow-0.10/.github/ISSUE_TEMPLATE/enhancement_request.md000066400000000000000000000004621513255534100235670ustar00rootroot00000000000000--- name: Enhancement request about: Request an improvement over an existing feature that's unrelated to a bug title: '' labels: 'enhancement' assignees: '' --- **Description:** [Summarize your suggestion] **Type:** [Code Style, Refactor, Documentation, Others] **Why:** [Argument why we want this] kworkflow-0.10/.github/ISSUE_TEMPLATE/feature_request.md000066400000000000000000000010521513255534100227310ustar00rootroot00000000000000--- name: Feature request about: New feature request title: '' labels: 'New feature request' assignees: '' --- **Description:** [Summarize your feature request] **Why:** [Explain why do we want this feature] **Targeted users:** [Try to describe who'd be using this feature. For example, if you think this will be helpful for maintainers, developers, newcomers, etc] **API draft:** [Describe your conception of the ideal API for this feature. Do not shy away from details here, and please explain the parameters and internals as best as you can] kworkflow-0.10/.github/workflows/000077500000000000000000000000001513255534100170605ustar00rootroot00000000000000kworkflow-0.10/.github/workflows/integration_tests.yml000066400000000000000000000007151513255534100233530ustar00rootroot00000000000000name: 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 kworkflow-0.10/.github/workflows/shellcheck_reviewdog.yml000066400000000000000000000012261513255534100237640ustar00rootroot00000000000000name: shellcheck-reviewdog on: [push, pull_request] jobs: shellcheck: name: runner / shellcheck runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: shellcheck uses: reviewdog/action-shellcheck@v1 with: github_token: ${{ secrets.github_token }} reporter: github-pr-review level: info filter_mode: added # This determines the scope of what reviewdog will report fail_on_error: true path: "." pattern: "*.sh" shellcheck_flags: "--external-sources --shell=bash --exclude=SC2016,SC2181,SC2034,SC2154,SC2001,SC1090,SC1091,SC2120" kworkflow-0.10/.github/workflows/shfmt.yml000066400000000000000000000011341513255534100207230ustar00rootroot00000000000000name: formatter-shfmt on: [push, pull_request] jobs: sh-checker: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Run the sh-checker uses: luizm/action-sh-checker@v0.3.0 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} SHFMT_OPTS: -i=2 -ln=bash -fn -ci -sr # arguments to shfmt. with: sh_checker_comment: true sh_checker_exclude: "documentation images sounds etc" sh_checker_shfmt_disable: false sh_checker_shellcheck_disable: true sh_checker_checkbashisms_enable: false kworkflow-0.10/.github/workflows/test_setup_and_docs.yml000066400000000000000000000014651513255534100236420ustar00rootroot00000000000000name: Test setup and doc build on: [push, pull_request] jobs: setup-and-doc-build: runs-on: ubuntu-latest defaults: run: shell: bash steps: - name: Checkout repository uses: actions/checkout@v4 # This is here just because git-email cannot be installed in the # Github CI otherwise. - name: Add git-core PPA for git-email run: | sudo add-apt-repository ppa:git-core/ppa -y - name: Update the system run: | sudo apt update -y - name: Install dependencies run: | sudo apt install -y python3-docutils python3-sphinx graphviz - name: Check documentation run: | ./setup.sh --docs --force - name: Check installation run: | ./setup.sh -i --force kworkflow-0.10/.github/workflows/unit_tests.yml000066400000000000000000000013361513255534100220070ustar00rootroot00000000000000name: Unit tests on: [push, pull_request] jobs: unit-tests: runs-on: ubuntu-latest defaults: run: shell: bash steps: - name: Checkout repository uses: actions/checkout@v4 with: fetch-depth: 3 - name: Update the system run: | sudo apt update -y - name: Install dependencies run: | sudo apt install -y shunit2 bc sqlite3 bsdmainutils libxml-xpath-perl fish - name: Prepare for tests run: | ./run_tests.sh prepare git config --global user.email "kw@kworkflow.net" git config --global user.name "Kworkflow" - name: Unit tests run: | ./run_tests.sh --unit kworkflow-0.10/.gitignore000066400000000000000000000003041513255534100154500ustar00rootroot00000000000000# Tests tests/shunit2 .checkpatch-camelcase.git. .checkpatch-camelcase.date.* tests/external tests/.tmp_kw_config_loader_test tests/.tmp build/ kcov_out/ # Pip virtualenv folder docs_virtual_env kworkflow-0.10/.pre-commit-config.yaml000066400000000000000000000007631513255534100177520ustar00rootroot00000000000000repos: - repo: local hooks: - id: shfmt name: shfmt minimum_pre_commit_version: 2.4.0 language: golang additional_dependencies: [mvdan.cc/sh/v3/cmd/shfmt@v3.3.0] entry: shfmt args: [-w, -i=2, -ln=bash, -fn, -ci, -sr] types: [shell] - id: shellcheck name: shellcheck language: script entry: /usr/bin/env shellcheck args: [-e, "SC2016,SC2181,SC2034,SC2154,SC2001,SC1090,SC1091,SC2120", -x, --shell=bash] types: [shell] kworkflow-0.10/LICENSE000066400000000000000000000432541513255534100145000ustar00rootroot00000000000000 GNU GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright (C) 1989, 1991 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Lesser General Public License instead.) You can apply it to your programs, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it. For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all. The precise terms and conditions for copying, distribution and modification follow. GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you". Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does. 1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License. c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.) These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. 3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following: a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.) The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code. 4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it. 6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. 7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. 9. The Free Software Foundation may publish revised and/or new versions of the 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 Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation. 10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Also add information on how to contact you by electronic and paper mail. If the program is interactive, make it output a short notice like this when it starts in an interactive mode: Gnomovision version 69, Copyright (C) year name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program. You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (which makes passes at compilers) written by James Hacker. , 1 April 1989 Ty Coon, President of Vice This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. kworkflow-0.10/README.md000066400000000000000000000034371513255534100147510ustar00rootroot00000000000000kworkflow ![Build Status](https://github.com/kworkflow/kworkflow/actions/workflows/unit_tests.yml/badge.svg?branch=master) # About kw has a simple mission: reduce the setup overhead of working with the Linux kernel and provide tools to support developers in their daily tasks. If you have a set of repeatable tasks that you usually perform while working in your favorite kernel subsystem or similar, consider adding it as a part of kw. # Install Take a look at [Install and Uninstall](documentation/content/installanduninstall.rst). # How to If you want to know more about kw's usage and its commands, take a look at [Kw man](documentation/man/kw.rst) or, with kw installed, run `kw man`. # Tests If you want to know more about kw's tests take a look at [kw tests](documentation/content/tests.rst). # Generate Sphinx Documentation If you want to generate the Sphinx documentation, you can use: ``` ./setup.sh --docs ``` Finally, you can use your browser to look at the **index.html** page. For example: ``` firefox build/index.html ``` # Contributing We are happy that you want to help us! If you are looking for a good starting point, check [those issues](https://github.com/kworkflow/kworkflow/issues?q=is%3Aopen+label%3A%22good+first+issue%22+-label%3A%22done%3A+wait+for+stable%22) and don't forget to read our [Contribuitor's Guide](https://kworkflow.org/content/howtocontribute.html) (or [howtocontribute file](documentation/content/howtocontribute.rst)). # Reach Out The best way to get help or make suggestions is by creating [issues](https://github.com/kworkflow/kworkflow/issues) or making a [pull request](https://github.com/kworkflow/kworkflow/pulls), someone is likely to reply to these in little time. # License Kworkflow is under GPL-2.0+ kworkflow-0.10/database/000077500000000000000000000000001513255534100152275ustar00rootroot00000000000000kworkflow-0.10/database/kwdb.sql000066400000000000000000000150331513255534100167010ustar00rootroot00000000000000PRAGMA foreign_keys = 1; BEGIN TRANSACTION; -- Tables -- This table holds the metadata of the config files handled by kw CREATE TABLE IF NOT EXISTS "kernel_config" ( "id" INTEGER NOT NULL UNIQUE, "name" TEXT NOT NULL UNIQUE, "description" TEXT, "path" TEXT NOT NULL UNIQUE, "last_updated_datetime" TEXT NOT NULL, PRIMARY KEY("id") ); -- This table holds the names of the commands that kw keeps track of, like -- build and deploy CREATE TABLE IF NOT EXISTS "command_label" ( "id" INTEGER NOT NULL UNIQUE, "name" TEXT NOT NULL UNIQUE, PRIMARY KEY("id") ); -- Table containing the possible exit status of an executed commmand CREATE TABLE IF NOT EXISTS "status" ( "id" INTEGER NOT NULL UNIQUE, "name" TEXT NOT NULL UNIQUE, PRIMARY KEY("id") ); -- Table containing user created tags CREATE TABLE IF NOT EXISTS "tag" ( "id" INTEGER NOT NULL UNIQUE, "name" TEXT NOT NULL UNIQUE, -- The 'active' attribute is a boolean to denote if the tag is active -- or not. This is useful for listing just a subset of tags in the DB "active" INTEGER NOT NULL CHECK ("active" IN (0, 1)) DEFAULT 1, PRIMARY KEY("id") ); -- This is the table that holds the events triggered by kw, currently pertains -- to the executed commands that are saved and the pomodoro sessions created CREATE TABLE IF NOT EXISTS "event" ( "id" INTEGER NOT NULL UNIQUE, "date" TEXT NOT NULL, "time" TEXT, PRIMARY KEY("id") ); -- This is the relationship between an "event" that executes a given -- "command_label" CREATE TABLE IF NOT EXISTS "executed" ( "id" INTEGER NOT NULL UNIQUE, "command_label_id" INTEGER NOT NULL, "elapsed_time_in_secs" INTEGER NOT NULL, "status_id" INTEGER NOT NULL, PRIMARY KEY("id"), FOREIGN KEY("id") REFERENCES "event"("id") ON UPDATE CASCADE ON DELETE CASCADE, FOREIGN KEY("command_label_id") REFERENCES "command_label"("id") ON UPDATE CASCADE ON DELETE RESTRICT, FOREIGN KEY("status_id") REFERENCES "status"("id") ON UPDATE CASCADE ON DELETE RESTRICT ); -- Table containing the information related to each pomodoro timebox CREATE TABLE IF NOT EXISTS "timebox" ( "id" INTEGER NOT NULL UNIQUE, "duration" INTEGER NOT NULL, "description" TEXT, "tag_id" INTEGER NOT NULL, PRIMARY KEY("id"), FOREIGN KEY("id") REFERENCES "event"("id") ON UPDATE CASCADE ON DELETE CASCADE, FOREIGN KEY("tag_id") REFERENCES "tag"("id") ON UPDATE CASCADE ON DELETE RESTRICT ); -- Populate commands and status tables INSERT OR IGNORE INTO "status" ("name") VALUES ('success'), ('failure'), ('interrupted'), ('unknown'); INSERT OR IGNORE INTO "command_label" ("name") VALUES ('backup'), ('bd'), ('build'), ('clear-cache'), ('codestyle'), ('config'), ('debug'), ('deploy'), ('device'), ('diff'), ('drm'), ('env'), ('explore'), ('init'), ('kernel_config_manager'), ('list'), ('mail'), ('maintainers'), ('man'), ('modules_deploy'), ('pomodoro'), ('remote'), ('report'), ('self-update'), ('ssh'), ('uninstall'), ('vm'); -- Views -- This view shows the currently active pomodoro sessions CREATE VIEW IF NOT EXISTS "active_timebox" AS SELECT "e_id" AS "id", "tag", "date", "time", "duration", "description" FROM (SELECT "id" AS "e_id", "date", "time" FROM "event" ORDER BY "date") JOIN "timebox" ON "e_id" IS "timebox"."id" JOIN (SELECT "id" AS "g_id", "name" AS "tag" FROM "tag") ON "g_id" IS "timebox"."tag_id" WHERE CAST (strftime('%s',"date"||'T'||"time",'utc') + "duration" AS INTEGER) >= CAST (strftime('%s','now') AS INTEGER); -- This view aggregates all the pomodoro sessions on record CREATE VIEW IF NOT EXISTS "pomodoro_report" AS SELECT "e_id" AS "id", "tag_id", "name" AS "tag_name", "date", "time", "duration", "description" FROM (SELECT "id" AS "e_id", "date", "time" FROM "event") JOIN "timebox" ON "timebox"."id" IS "e_id" JOIN "tag" ON "tag"."id" IS "timebox"."tag_id"; -- This view aggregates all data relevant to the statistics reports CREATE VIEW IF NOT EXISTS "statistics_report" AS SELECT "e_id" AS "id", "name" AS "label_name", "status_name" AS "status", "date", "time", "elapsed_time_in_secs" FROM (SELECT "id" AS "e_id", "date", "time" FROM "event") JOIN "executed" ON "executed"."id" IS "e_id" JOIN "command_label" ON "command_label"."id" IS "executed"."command_label_id" JOIN (SELECT "id" AS "s_id", "name" AS "status_name" FROM "status") ON "s_id" IS "executed"."status_id"; -- Indexes CREATE INDEX IF NOT EXISTS "command_label_idx" ON "command_label" ( "name" ASC, "id" ); CREATE INDEX IF NOT EXISTS "tag_idx" ON "tag" ( "active" DESC, "name" ASC, "id" ); CREATE INDEX IF NOT EXISTS "chronological_events" ON "event" ( "date" ASC, "time" ASC, "id" ); CREATE INDEX IF NOT EXISTS "executed_idx" ON "executed" ( "command_label_id" ASC, "status_id" ASC, "elapsed_time_in_secs" DESC, "id" ); CREATE INDEX IF NOT EXISTS "timebox_idx" ON "timebox" ( "tag_id" ASC, "duration" DESC, "id", "description" ); -- Triggers CREATE TRIGGER IF NOT EXISTS "delete_pomodoro" INSTEAD OF DELETE ON "pomodoro_report" BEGIN DELETE FROM "timebox" WHERE "timebox"."id" IS "OLD"."id"; DELETE FROM "event" WHERE "event"."id" IS "OLD"."id"; END; CREATE TRIGGER IF NOT EXISTS "delete_statistics" INSTEAD OF DELETE ON "statistics_report" BEGIN DELETE FROM "executed" WHERE "executed"."id" IS "OLD"."id"; DELETE FROM "event" WHERE "event"."id" IS "OLD"."id"; END; CREATE TRIGGER IF NOT EXISTS "insert_pomodoro" INSTEAD OF INSERT ON "pomodoro_report" BEGIN INSERT OR IGNORE INTO "tag" ("name") VALUES ("NEW"."tag_name"); INSERT INTO "event" ("date", "time") VALUES ("NEW"."date", "NEW"."time"); INSERT INTO "timebox" ("id","duration","description","tag_id") VALUES( last_insert_rowid(), "NEW"."duration", "NEW"."description", (SELECT "id" FROM "tag" AS "g" WHERE "g"."name" IS "NEW"."tag_name") ); END; CREATE TRIGGER IF NOT EXISTS "insert_statistics" INSTEAD OF INSERT ON "statistics_report" BEGIN INSERT OR IGNORE INTO "command_label" ("name") VALUES ("NEW"."label_name"); INSERT OR IGNORE INTO "status" ("name") VALUES ("NEW"."status"); INSERT INTO "event" ("date", "time") VALUES ("NEW"."date", "NEW"."time"); INSERT INTO "executed" ("id", "command_label_id", "status_id", "elapsed_time_in_secs") VALUES ( last_insert_rowid(), (SELECT "id" FROM "command_label" AS "c" WHERE "c"."name" IS "NEW"."label_name"), (SELECT "id" FROM "status" AS "s" WHERE "s"."name" IS "NEW"."status"), "NEW"."elapsed_time_in_secs" ); END; COMMIT; kworkflow-0.10/database/migrate_legacy_data_20220101.sh000077500000000000000000000167261513255534100225160ustar00rootroot00000000000000#!/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 declare -r KW_LIB_DIR='src' . "${KW_LIB_DIR}/lib/kw_include.sh" --source-only include "${KW_LIB_DIR}/lib/kwio.sh" include "${KW_LIB_DIR}/lib/kwlib.sh" include "${KW_LIB_DIR}/lib/kw_string.sh" include "${KW_LIB_DIR}/lib/kw_time_and_date.sh" include "${KW_LIB_DIR}/lib/kw_db.sh" declare -r KW_DB_DIR='database' declare -r app_name='kw' declare -r datadir="${XDG_DATA_HOME:-"${HOME}/.local/share"}/${app_name}" declare -gr KW_DATA_DIR=${KW_DATA_DIR:-"$datadir"} function db_migration_main() { execute_sql_script "${KW_DB_DIR}/kwdb.sql" if [[ "$?" != 0 ]]; then complain 'Creation of database schema has failed. Aborting migration.' return 1 # EPERM fi migrate_statistics || { complain 'Migration of statistics reports has failed. Aborting migration.' return 1 # EPERM } migrate_pomodoro || { complain 'Migration of pomodoro reports has failed. Aborting migration.' return 1 # EPERM } migrate_kernel_configs || { complain 'Migration of kernel configs has failed. Aborting migration.' return 1 # EPERM } execute_command_db 'PRAGMA optimize;' } function migrate_statistics() { local -a file_list local start_date local label_name local status local elapsed_time_in_secs local rows local columns='("date","label_name","status","elapsed_time_in_secs")' local count=0 local -a values=() # if there are no statistics reports to migrate, return [[ ! -d "${datadir}/statistics" ]] && return 0 file_list=$(find "${datadir}/statistics" -type f | sort --dictionary-order) for file in $file_list; do # This line converts the file path into a usable date value # E.g.: ${datadir}/statistics/2021/10/05 -> 2021-10-05 start_date=$(printf '%s\n' "$file" | sed -e 's/.*statistics\///' -e 's/\//-/g') while IFS=' ' read -r label_name elapsed_time_in_secs; do status='success' # The new database stores execution status, making this label unnecessary if [[ "$label_name" == 'build_failure' ]]; then status='failure' label_name='build' elif [[ "$label_name" == 'deploy_failure' ]]; then status='failure' label_name='deploy' fi label_name="$(str_lowercase "$label_name")" values+=("$start_date" "$label_name" "$status" "$elapsed_time_in_secs") ((count++)) # insert statements have a limit on the amount of values being inserted # at once, this ensures that limit is never reached if [[ "$count" -ge 100 ]]; then rows="$(format_values_db 4 "${values[@]}")" insert_into '"statistics_report"' "$columns" "$rows" values=() count=0 fi done < "$file" done # if there are values left, insert them if [[ "${#values}" != 0 ]]; then rows="$(format_values_db 4 "${values[@]}")" insert_into '"statistics_report"' "$columns" "$rows" fi # mark migrated directory to avoid duplicated data cmd_manager 'SILENT' "mv ${datadir}/statistics ${datadir}/legacy_statistics" if [[ "$?" != 0 ]]; then complain "Couldn't rename ${datadir}/statistics ${datadir}/legacy_statistics" return 1 # EPERM fi } function migrate_pomodoro() { local -a file_list local line local tag_name local start_date local start_time local duration local description local rows local columns='("tag_name","date","time","duration","description")' local count=0 local -a values=() # if there are no pomodoro reports to migrate, return [[ ! -d "${datadir}/pomodoro" ]] && return 0 file_list=$(find "${datadir}/pomodoro" -type f | sort --dictionary-order) for file in $file_list; do # avoid processing tags file [[ "$file" =~ tags$ ]] && continue # This line converts the file path into a usable date value # E.g.: ${datadir}/pomodoro/2021/10/05 -> 2021-10-05 start_date=$(printf '%s\n' "$file" | sed -e 's/.*pomodoro\///' -e 's/\//-/g') while read -r line; do tag_name=$(printf '%s\n' "$line" | cut -d ',' -f1) duration=$(printf '%s\n' "$line" | cut -d ',' -f2) start_time=$(printf '%s\n' "$line" | cut -d ',' -f3) description=$(printf '%s\n' "$line" | cut -d ',' -f1,2,3 --complement) [[ -z "$description" ]] && description='NULL' duration=$(timebox_to_sec "$duration") values+=("$tag_name" "$start_date" "$start_time" "$duration" "$description") ((count++)) # insert statements have a limit on the amount of values being inserted # at once, this ensures that limit is never reached if [[ "$count" -ge 100 ]]; then rows="$(format_values_db 5 "${values[@]}")" insert_into '"pomodoro_report"' "$columns" "$rows" values=() count=0 fi done < "$file" done # if there are values left, insert them if [[ "${#values}" != 0 ]]; then rows="$(format_values_db 5 "${values[@]}")" insert_into '"pomodoro_report"' "$columns" "$rows" fi # mark migrated directory to avoid duplicated data cmd_manager 'SILENT' "mv ${datadir}/pomodoro ${datadir}/legacy_pomodoro" if [[ "$?" != 0 ]]; then complain "Couldn't rename ${datadir}/pomodoro ${datadir}/legacy_pomodoro" return 1 # EPERM fi } function migrate_kernel_configs() { local -a file_list local line local name local path local description local rows local columns='("name","description","path","last_updated_datetime")' local count=0 local -a values=() local configs_dir="${datadir}/configs/configs" local metadata_dir="${datadir}/configs/metadata" # if there are no kernel config files to migrate, return [[ ! -d "$configs_dir" ]] && return 0 file_list=$(find "$configs_dir" -type f | sort --dictionary-order) for file in $file_list; do # the kernel config files will reside in 'KW_DATA_DIR/configs', so update path path=$(printf '%s' "$file" | sed 's/configs\///') name="${path##*/}" # get just the file name description=$(< "${metadata_dir}/${name}") last_updated_datetime=$(date '+%Y-%m-%d %H:%M:%S') [[ -z "$description" ]] && description='NULL' values+=("$name" "$description" "$path" "$last_updated_datetime") ((count++)) # insert statements have a limit on the amount of values being inserted # at once, this ensures that limit is never reached if [[ "$count" -ge 100 ]]; then rows="$(format_values_db 4 "${values[@]}")" insert_into '"kernel_config"' "$columns" "$rows" values=() count=0 fi done # if there are values left, insert them if [[ "${#values}" != 0 ]]; then rows="$(format_values_db 4 "${values[@]}")" insert_into '"kernel_config"' "$columns" "$rows" fi # copy the kernel config files to the parent directory ('KW_DATA_DIR/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 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 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 fi } db_migration_main kworkflow-0.10/database/pre_cmd.sql000066400000000000000000000000311513255534100173530ustar00rootroot00000000000000PRAGMA foreign_keys = 1; kworkflow-0.10/documentation/000077500000000000000000000000001513255534100163345ustar00rootroot00000000000000kworkflow-0.10/documentation/conf.py000066400000000000000000000200011513255534100176240ustar00rootroot00000000000000# -*- coding: utf-8 -*- # # Configuration file for the Sphinx documentation builder. # # This file does only contain a selection of the most common options. For a # full list see the documentation: # http://www.sphinx-doc.org/en/master/config # -- Path setup -------------------------------------------------------------- # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # import os import sys sys.path.insert(0, os.path.abspath('..')) # -- Project information ----------------------------------------------------- project = 'kw' copyright = '2019, Rodrigo Siqueira, Matheus Tavares' author = 'Rodrigo Siqueira, Matheus Tavares' # The short X.Y version version = '' # The full version, including alpha/beta/rc tags release = '' # -- General configuration --------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. # # needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.coverage', # Not needed for now, and it's not supported on older versions of Sphinx #'sphinx.ext.imgmath', 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', 'sphinx.ext.graphviz', ] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] source_suffix = '.rst' # The master toctree document. master_doc = 'index' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. language = 'en' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. exclude_patterns = [] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # try: import sphinx_book_theme html_theme = 'sphinx_book_theme' except ImportError: sys.stdout.write('We could not find the book theme used on our website. You can install it using: pip install sphinx-book-theme.\n') sys.stdout.write('For now, kw will assume the default theme - Alabaster\n') html_theme = 'alabaster' html_favicon = 'favicon.ico' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # html_theme_options = { "navigation_with_keys": False } # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = [] # Custom sidebar templates, must be a dictionary that maps document names # to template names. # # The default sidebars (for documents that don't match any pattern) are # defined by theme itself. Builtin themes are using these templates by # default: ``['localtoc.html', 'relations.html', 'sourcelink.html', # 'searchbox.html']``. # # html_sidebars = {} # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. htmlhelp_basename = 'KernelWorkflowdoc' # -- Options for LaTeX output ------------------------------------------------ latex_elements = { # The paper size ('letterpaper' or 'a4paper'). # # 'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). # # 'pointsize': '10pt', # Additional stuff for the LaTeX preamble. # # 'preamble': '', # Latex figure (float) alignment # # 'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, 'KernelWorkflow.tex', 'KernelWorkflow Documentation', 'Rodrigo Siqueira, Matheus Tavares', 'manual'), ] # -- Options for manual page output ------------------------------------------ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ ('man/kw', 'kw', 'KernelWorkflow Documentation', [author], 1), ('man/features/kw-backup', 'kw-backup', 'save and restore kw data', [author], 1), ('man/features/kw-build', 'kw-build', 'build the kernel', [author], 1), ('man/features/kw-codestyle', 'kw-codestyle', 'checkpatch wrapper', [author], 1), ('man/features/kw-kernel-config-manager', 'kw-kernel-config-manager', 'config manager', [author], 1), ('man/features/kw-config', 'kw-config', 'config manager', [author], 1), ('man/features/kw-env', 'kw-env', 'kw env manager', [author], 1), ('man/features/kw-remote', 'kw-remote', 'Manage set of tracked test machines', [author], 1), ('man/features/kw-debug', 'kw-debug', 'kernel debug', [author], 1), ('man/features/kw-deploy', 'kw-deploy', 'deploy the kernel', [author], 1), ('man/features/kw-device', 'kw-device', 'hardware information', [author], 1), ('man/features/kw-diff', 'kw-diff', 'useful diff wrapper', [author], 1), ('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-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-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', 'Terminal UI to interact with patches from lore.kernel.org', ['David Tadokoro, Rodrigo Siqueira'], 1), ('man/features/kw-bd', 'kw-bd', 'build and then deploy the kernel', ['Briza Mel de Sousa, Lorenzo Salvador'], 1), ] # -- Options for Texinfo output ---------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ (master_doc, 'KernelWorkflow', 'KernelWorkflow Documentation', author, 'KernelWorkflow', 'Inglorious kernel developer workflow tool', 'Miscellaneous'), ] # -- Options for Epub output ------------------------------------------------- # Bibliographic Dublin Core info. epub_title = project # The unique identifier of the text. This can be a ISBN number # or the project homepage. # # epub_identifier = '' # A unique identification for the text. # # epub_uid = '' # A list of files that should not be packed into the epub file. epub_exclude_files = ['search.html'] # -- Extension configuration ------------------------------------------------- # -- Options for todo extension ---------------------------------------------- # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True kworkflow-0.10/documentation/content/000077500000000000000000000000001513255534100200065ustar00rootroot00000000000000kworkflow-0.10/documentation/content/awesome_kw.rst000066400000000000000000000006501513255534100227020ustar00rootroot00000000000000================================== Awesome Kworkflow Related Projects ================================== Awesome Kworkflow page is a curated list of KW resources that might improve your experience using kw and other external projects associated with it. .. contents:: Nushell ------- Nushell completions can be found at nu_scripts_. .. _nu_scripts: https://github.com/nushell/nu_scripts/tree/main/custom-completions/kw kworkflow-0.10/documentation/content/codingstyle.rst000066400000000000000000000276121513255534100230740ustar00rootroot00000000000000===================== kw coding style ===================== .. _coding-style: .. contents:: :depth: 1 :local: :backlinks: none .. highlight:: console Overview -------- This is a document describing the kw preferred coding style. It is important to highlight that we got inspiration from Linux_ and Git_ code style; for this reason, we copied and pasted many pieces from both projects. .. _Git: https://github.com/git/git/blob/master/Documentation/CodingGuidelines#L41 .. _Linux: https://github.com/torvalds/linux/blob/master/Documentation/process/coding-style.rst .. _shfmt-label: shfmt _____ To help us enforce our codestyle decisions we utilize the `shfmt `_ code formatter in our CI pipeline. Please refer to the shfmt repository for instructions on how to install it on your specific linux distribution, it is available as a package for most distributions and as a plugin for most IDEs and text editors. To format a file using shfmt:: shfmt -w -i=2 -ln=bash -fn -ci -sr FILE To check a file and error with a diff when the formatting differs:: shfmt -d -i=2 -ln=bash -fn -ci -sr FILE Indentation ----------- We adopt two whitespace indentations. Avoid tricky expression ----------------------- We try to keep things as simple as possible in kw, for this reason, we try to **avoid**: * Multiple assignments on a single line; * Using more than 10 local variables per function. .. note:: Of course, we value the code legibility, for this reason, we accept a few exceptions. Breaking long lines and strings ------------------------------- The default limit on the length of lines is 80 columns and this is a strongly preferred limit. This is not a rule to be blindly followed, we understand that in some cases we need more columns; however, try to do you best for keeping the code under 80 characters. Sometimes long strings are a bit cumbersome to keep under 80 columns, in kw we adopt string concatenation for this case as the example below illustrates:: my_long_string="kw ran into an unrecoverable error while trying to parse your file." my_long_string+=" Do you wish to continue anyway [Y/n]?" Placing Optional Bash Keywords and Spaces ----------------------------------------- Some of the bash keywords may accept or not the reserved word ``then`` or ``do`` which can be added at the end of the expression or in the next line. In kw we put the ``then`` statement at the end of the expression (after the semicolon), as the example below illustrates:: if [[ ]]; then do_something fi The same idea applies for loops:: for ; do do_something done or:: while ; do do_something done For the ``case`` statement, we add one level of indentation after the ``case`` statement:: case in option1) do_something1 ;; option2) do_something2 ;; *) exit 22 ;; esac Functions --------- .. note:: Our approach for implementing function is really similar to the ones adopted by the Linux Kernel, the description here is an adaptation of the Linux Kernel codestyle documentation. Functions should be short and sweet, and do just one thing. They should fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, as we all know), and do one thing and do that well. The maximum length of a function is inversely proportional to the complexity and indentation level of that function. So, if you have a conceptually simple function that is just one long (but simple) case-statement, where you have to do lots of small things for a lot of different cases, it’s OK to have a longer function. However, if you have a complex function, and you suspect that a less-than-gifted first-year high-school student might not even understand what the function is all about, you should adhere to the maximum limits all the more closely. Use helper functions with descriptive names. Another measure of the function is the number of local variables. They shouldn’t exceed 5-10, or you’re doing something wrong. Re-think the function, and split it into smaller pieces. A human brain can generally easily keep track of about 7 different things, anything more and it gets confused. You know you’re brilliant, but maybe you’d like to understand what you did 2 weeks from now. Bash supports function declarations with or without the parentheses and with or without the reserved word ``function``. In kw source code, we **always** add the ``function`` reserved word and the parentheses even if the function does not have any parameter (without an extra space). Additionally, we add the curly braces in a single line. For example:: function modules_install_to() { [..] } For the function returning we try to respect the errno codes, for example:: function mk_list_installed_kernels { [..] if [ "$?" != 0 ] ; then complain "Did you check if your VM is running?" return 125 # ECANCELED fi [..] } As you can notice from the examples, we use snake case for function definitions, this is valid for all the kw code. Command substitution and arithmetic expression ---------------------------------------------- We prefer ``$( ... )`` for command substitution; unlike \`\`, it properly nests. When using command substitution to access the contents of a file the cat command (``$(cat )``) can be replaced with a ``<`` which is equivalent but faster (``$(< )``). E.g.: ``$(cat "$file") => $(< "$file")`` For arithmetic expansion we use ``(( ... ))``. Check for command ----------------- If you want to find out if a command is available on the user's ``$PATH``, you should use the function ``command_exists()`` available under kw lib. If you are working in a plugin or have a strong reason not to use ``command_exists()``, you should use ``command`` instead of ``which`` since the letter is not machine parsable and its exit code is not reliable across platforms. How to include/import files --------------------------- Do not source code using ``.`` or ``source`` unless you have a very strong argument. We have a helper function for that named ``include`` in `kw_include.sh` and it should be used any and every time a file needs to be sourced, ``. file.sh --source-only`` should only be used to source `include.sh` itself. The ``include`` function guarantees us that no file will be sourced twice, making the kw dev life easier with one thing less to worry about. Test function name ------------------ Tests are an important part of kw, we only accept new features with tests, and we prefer bug fixes that come with tests. For trying to keep the test comprehensible, we adopt the following pattern for naming a test:: test_target_function_name_[_]() To better illustrate this definition, see the example below:: function test_detect_distro() This function name indicates that we are testing ``detect_distro`` function. Another example:: function test_save_config_file_check_description() The function ``save_config_file`` is tested with a focus on description validation. Resources for tests ------------------- We encourage the use of the following features offered by shunit2, kworkflow's unit test framework. - Functions ``oneTimeSetUp`` and ``oneTimeTearDown``: If defined, these functions will be called once before and after any tests are run, respectively. Notice that shunit2 is sourced once for each test file, so the scope of these functions is effectively the test file (e.g. `help_test.sh`) in which they are defined. - Functions ``setUp`` and ``tearDown``: If defined, these functions will be called before and after each test (i.e. a test function) is run, respectively. - Shunit2 offers a temporary directory that will be cleaned upon it's exit. The path to this directory is stored in the variable ``SHUNIT_TMPDIR``. Note however that this directory is not cleaned up between tests, so you may need to clear it in the ``tearDown`` function. We also encourage each assertion in each test to be identified with the variable ``LINENO``. This variable expands to the line number currently being executed. This way the origin of an error message can quickly be identified by 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)" "$expected_output" "$output" or:: assertEquals "($LINENO)" "$expected_output" "$output" Help functions -------------- Each subcommand may have its help function that details its usage. This function should be located as close as possible to the feature they document; ideally, we want it in the same file. For example, you should find details on using the ``build`` option in the ``build.sh``, and for ``kernel-config-manager`` in the file `kernel_config_manager.sh`. Handling Signals ---------------- It is natural for commands to set global variables or to create temporary files during their execution. However, all commands should expect to receive signals and be able to properly handle them. If you implement a new feature, take some time to check if it pollutes the environment. If it does, make sure to handle it's de-pollution upon receiving a SIGINT or a SIGTERM: an interrupted command should always leave the environment in the same state as it was prior to its invocation. Convenience functions for this purpose (setting and resetting handlers for arbitrary signals) are implemented in `src/signal_manager`. Use ``printf`` instead of ``echo`` ---------------------------------- We stay away from ``echo`` as it is not always consistent with its output depending on system and bash version. Therefore always use ``printf`` instead, 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 -------------------- If you have any type of string concatenation, always use ``${}``. For example:: kernel_path="${PWD}/" kw_path="${HOME}/.local/.config" How to handle return -------------------- When handling return value and its manipulation inside kw, use the errno code pattern. By adopting this pattern, we standardize the expected errors and provide meaningful error codes for the user. Finally, always add a comment next to the return value with the string reference to it, for example:: return 22 # EINVAL return 2 # ENOENT Avoid short options ------------------- Usually, commands available in the terminal provide two ways of passing the same option: through a short option and through a long option. The short options are convenient for daily use; however, for writing kw code it is better to use the long option because it is more human readable. See the below example: Bad:: rsync -vr dir1 dir2 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 ---------- When in doubt of a coding style matter not specified in this file, it is always a good idea to search how other sections of the codebase use the term you are in doubt about. But be aware that some sections may unfortunately be at odds with the specified style rules (and pull requests to correct them are very welcome). Finally, feel free to also suggest modifications to this document -- to add absent rules -- or mention any style doubts in your pull request. kworkflow-0.10/documentation/content/dev_cycle.dot000066400000000000000000000007371513255534100224620ustar00rootroot00000000000000digraph dev_cycle { node [fontname = "arial"] edge [fontname = "arial" arrowhead = "none"] { node [margin=0 fontcolor=blue shape=ellipse style=filled] master [fillcolor=yellow label="Master"] unstable [fillcolor=yellow label="Unstable"] } "Bug fixes" -> "Patch"; "New features" -> "Patch"; "Etc." -> "Patch"; "Patch" -> unstable [label=" PR" arrowhead = "vee"]; unstable -> master [label=" Merge" arrowhead = "vee"]; } kworkflow-0.10/documentation/content/developmentworkflow.rst000066400000000000000000000160731513255534100246640ustar00rootroot00000000000000======================== Development workflow ======================== .. contents:: :depth: 1 :local: :backlinks: none .. highlight:: console kw is developed using Git and is hosted at Github. If you want to understand our development workflow better, clone the repository to have a local copy:: git clone https://github.com/kworkflow/kworkflow.git Install ------- Installing kw is one of the first steps to understanding its development workflow. After cloning the repository, read the page related to :ref:`installing and removing`. Tests ----- To make sure our code is working as it is supposed to, we add :ref:`tests` to check that. All our tests can be found in the `tests` folder. Notice that every test file name ends with test before the .sh extension (i.e. `build_test.sh` and `deploy_test.sh`). This is done so that the `run_tests.sh` file can detect those tests and run or list them. Unit tests ========== Unit testing is an essential part of our development workflow and we use the `shUnit2 `_ framework to write our tests. Ideally, every new function should have a test related to it. So, if you're working on a new feature, added a new function, or changed the behavior of an existing one, it's fundamental to make the necessary adjustments related to testing. To see how to run individual test files, check our :ref:`page on that`. Run kw without installing it ---------------------------- Apart from using the installed version of kw, you can also use your local version by going into it and running `./kw` with any other option you want, just like you would do when you run kw that is installed in your machine. For instance, suppose you changed the `help.sh` file and want to see if everything's working as expected. Inside the kw directory you're working on, you can just invoke:: ./kw help This is a convenient option when you're developing for kw and don't want to install it every time you make a new change to see the result. Running `./kw b` or `./kw d` won't work, though, since these two options require you to be inside a repository. Documentation ------------- As important as writing tests is documenting things. Our documentation is located in the `documentation` folder, and we use `Sphinx `_ to create it. Whether you changed the way a command behaves or added a new feature, modify the documentation accordingly and preferably with examples. Also, in the source code, we tend to comment on top of each function, explaining its usage. ShellCheck and shfmt -------------------- kw follows its own :ref:`code style guide`, and makes use of tools, such as ShellCheck and :ref:`shfmt`, to make sure this code style is being followed. Git pre-commit hook =================== A very handy way to ensure that your code is well-formatted and follows our standards is to have a pre-commit hook configured to run the aforementioned tools before committing. This may, for example, prevent code with bad syntax and wrong formatting from even being committed before having these things fixed. To configure this Git pre-commit hook: 0. Have shellcheck installed on your computer. 1. Install `pre-commit `_. 2. Create a file named `.pre-commit-config.yaml` in your local kw repository with the following YAML code: .. code-block:: yaml repos: - repo: local hooks: - id: shfmt name: shfmt minimum_pre_commit_version: 2.4.0 language: golang additional_dependencies: [mvdan.cc/sh/v3/cmd/shfmt@v3.3.0] entry: shfmt args: [-w, -i=2, -ln=bash, -fn, -ci, -sr] types: [shell] - id: shellcheck name: shellcheck language: script entry: /usr/bin/env shellcheck args: [-e, "SC2016,SC2181,SC2034,SC2154,SC2001,SC1090,SC1091,SC2120", -x, --shell=bash] types: [shell] .. note:: Notice that the pre-commit hook above sets a shfmt version, which is the same one we use in the Github actions. 3. Then, run:: pre-commit install The next time you try to commit your work, your pre-commit hook will run both shellcheck and shfmt, and warn you of any errors you may have made. Kwreview ======== Another way to have your code checked against ``shfmt`` and ``shellcheck`` is to use ``scripts/kwreview.sh``. By default, it will check your current patch (i.e. what has changed since the branch unstable) and print ``shellcheck``'s warnings and ``shfmt``'s warnings as diffs. Use ``kwreview -w`` to apply ``shfmt``'s changes to the files. If you supply it with path to shell files, it will analyse those. Make sure you have ``shfmt``, ``shellcheck`` and ``reviewdog`` installed (see :ref:`dependencies_label`). For vim users, it is possible to use ``kwreview.sh`` to populate the `quickfix `_ (or locations) window, making it easy to navigate the warnings and errors. As an example, consider adding the following lines to your ``.vimrc``:: function Kwreview(...) let arg = get(a:, 1, "") let &l:makeprg="scripts/kwreview.sh " . arg make execute ":e" endfunction command -nargs=* Kwreview :call Kwreview() Now you can call ``kwreview.sh`` with the vim command ``:Kwreview`` (notice the upper case initial) and navigate the errors/warnings with ``:copen``, ``:cn``, ``:cp``, etc. .. _dependencies_label: Dependencies ============ Installing ShellCheck ~~~~~~~~~~~~~~~~~~~~~ Shellcheck is available as a package for most distributions. On Debian based distros, use ``sudo apt install shellcheck``. On Arch based distros, use ``sudo pacman -S shellcheck``. Installing shfmt ~~~~~~~~~~~~~~~~ To install shfmt, ``go`` must be installed. On Debian based distros:: sudo apt install golang On arch based distros:: sudo pacman -S go With go installed, run the following command to install shfmt:: GO111MODULE=on go get mvdan.cc/sh/v3/cmd/shfmt More information can be found in their `github page `__. Installing pre-commit ~~~~~~~~~~~~~~~~~~~~~ ``pre-commit`` is available as a package for some distributions. On Debian based distros, try using ``sudo apt install pre-commit``. On Arch based distros, use ``sudo pacman -S python-pre-commit``. If that doesn't work, you can install it using pip with ``pip install pre-commit``. Installing reviewdog ~~~~~~~~~~~~~~~~~~~~ To install reviewdog, run the following command:: curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh | sh -s -- -b This will install reviewdog in the directory at ``path``. Make sure this directory is in your ``PATH`` environmental variable, so that reviewdog is executable from any directory. For example, you can install it in:: $HOME/bin/ And add the following line to you shell configuration file (e.g. ``~/.profile``):: if [ -d "$HOME/bin" ] ; then PATH="$HOME/bin:$PATH" fi Check out reviewdog's `github page `__ for other installation options. kworkflow-0.10/documentation/content/howtocontribute.rst000066400000000000000000000225231513255534100240030ustar00rootroot00000000000000===================== How to Contribute ===================== .. _how-to-contribute: .. contents:: :depth: 1 :local: :backlinks: none .. highlight:: console Overview -------- The Linux Kernel and Git community inspired our contribution process. As a result, this document is directly based on their contribution documentation. In particular, the text under `Commit Messages`_ and `Certify Your Work by Adding Your "Signed-off-by: " Line`_ have been directly taken from Git's SubmittingPatches doc (with some modifications). For the original document, please check `the git documentation `_. Development Cycle and Branches ------------------------------ Kw's development happens in GitHub. The official repository can be found `here `_. Our development cycle relies on two different branches: 1. **master**: We maintain the kw stable version in the master branch, and we try our best to keep master working well for final users. If you only want to use kw, this branch is perfect for you. 2. **unstable**: This branch has the kw latest version, and it is the development branch. If you want to contribute to kw, base your work in this branch. .. warning:: If you want to contribute to **kw**, use the **unstable** branch and send your pull requests to this branch. From time to time, when we feel happy with the unstable version, we merge the unstable branch into the master branch. The Figure below summarizes the development cycle. .. graphviz:: dev_cycle.dot :align: center .. note:: One of our main goals is to keep kw stable. In this sense, **if you send a new patch do not forget to add tests**. You might also want to fork `kw at github `_ and allow github actions for it, to automatically run tests in the cloud. If you want to know more about tests, take a look at our :ref:`About Tests` page. Commit Messages --------------- .. _`Commit Messages`: The first line of the commit message should be a short description (50 characters is the soft limit), and should skip the full stop. It is also conventional in most cases to prefix the first line with ": " where the is a filename or identifier for the general area of the code being modified, e.g. * setup: disable unnecessary download of checkpatch script * src: mk: remove unnecessary multiplication of PARALLEL_CORES If in doubt which identifier to use, run :code:`git log --no-merges` on the files you are modifying to see the current conventions. It's customary to start the remainder of the first line after ": " with a lower-case letter. E.g. "doc: clarify...", not "doc: Clarify...". (But as you might see in our log, that's a soft rule in **kw**.) The body should provide a meaningful commit message, which: * explains the problem the change tries to solve, i.e. what is wrong with the current code without the change. * justifies the way the change solves the problem, i.e. why the result with the change is better. * alternate solutions considered but discarded, if any. Describe your changes in imperative mood, e.g. *"make xyzzy do frotz"* instead of *"[This patch] makes xyzzy do frotz"* or *"[I] changed xyzzy to do frotz"*, as if you are giving orders to the codebase to change its behavior. Try to make sure your explanation can be understood without external resources. At the bottom of the message body, you might include references to the issues that the commit addresses. This can be something like ``Solves #30``, ``Fixes: #28`` or ``Closes #10``. Certify Your Work by Adding Your "Signed-off-by: " Line ------------------------------------------------------- .. _`Certify Your Work by Adding Your "Signed-off-by: " Line`: To improve tracking of who did what, we've borrowed the "sign-off" procedure from the Linux kernel project on patches that are being emailed around. Although core Git is a much smaller project it is a good discipline to follow it. The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify the below Developer's Certificate of Origin (D-C-O): .. important:: By making a contribution to this project, I certify that: 1. The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or 2. The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or 3. The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. 4. I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. then you just add a line saying:: Signed-off-by: Xpto Lalala Blabla This line can be automatically added by Git if you run the **git-commit** command with the :code:`-s` option. Notice that you can place your own **Signed-off-by**: line when forwarding somebody else's patch with the above rules for D-C-O. Indeed you are encouraged to do so. .. note:: Also notice that a real name should be used in the **Signed-off-by**: line. Please don't hide your real name. If you'd like to, you can put extra tags at the end: 1. **Reported-by**: is used to credit someone who found the bug that the patch attempts to fix. 2. **Acked-by**: says that the person who is more familiar with the area the patch attempts to modify liked the patch. 3. **Tested-by**: is used to indicate that the person applied the patch and found it to have the desired effect. 4. **Reviewed-by**: unlike the other tags, can only be offered by the reviewer and means that they are completely satisfied with the patch and it is ready for application. It is usually only offered after a detailed review. You can also create your own tag or use one that’s in common usage such as **Co-authored-by** or **Helped-by**. About Issue Labels ------------------ We use GitHub's issue and milestone trackers to help manage the kw project. We use issues to keep track of different things, as a result, we categorize all of them with labels; most of the available labels are self-explanatory. However, few of them deserve a brief explanation: * **done: wait for stable**: In the section *Development Cycle and Branches* we explained how our branch management works. Recall that we have an unstable branch that sooner or later will be merged into the master branch (stable). This label is used for identifying issues already solved on the unstable, but not landed in the master yet. If you see this label, feel free to test the feature/bugfix in the unstable branch. * **new feature request**: If you want to request or see a possible new feature, you should use this label. * **enhancement**: Similar to new feature, but could be an improvement of an old feature as well. * **good first issue**: If you started to use kw, and after that, you desire to contribute to it but you don't know where you could start, this label is the answer to your aspiration. * **optimization**: Issues that require optimization in kw. * **help wanted**: We don't know how to solve this or we don't have the time right now. Any help solving the issue will be highly appreciated. * **test**: Issues related to kw's test suite. Any kind of test or even the **run_tests.sh** script itself. * **bug**: Something is not working as expected. How we incorporate PRs ---------------------- In the kw project, we avoid the addition of extra commits per PR. For this reason, after we accept a contribution, we take it and apply it on top of the unstable branch. We only add a merge commit when we merge the unstable branch into the master branch, and usually, this commit has a summary of the new features brought from the unstable branch. Releases -------- We have a simple rule for making a release: *it'll be done when it's done*. If you want to follow our release plans, just take a look at our milestones_ and projects_ since we use those for self-organization. .. _milestones: https://github.com/kworkflow/kworkflow/milestones .. _projects: https://github.com/kworkflow/kworkflow/projects Reach Out --------- The best way to get help, or make suggestions is by creating issues_ or making a `pull request`_, someone is likely to reply to these in little time. And if you need in-person help or further guidance with **kw** you can try using the ``#kw-devel`` channel on the OFTC_ IRC server (**irc.oftc.net**). You can also try joining or opening a new discussion on the discussions_ page on github. .. _issues: https://github.com/kworkflow/kworkflow/issues .. _`pull request`: https://github.com/kworkflow/kworkflow/pulls .. _discussions: https://github.com/kworkflow/kworkflow/discussions .. _OFTC: https://www.oftc.net/ kworkflow-0.10/documentation/content/installanduninstall.rst000066400000000000000000000102401513255534100246200ustar00rootroot00000000000000======================= Install and Remove `kw` ======================= .. _install-and-remove-kw: .. contents:: :depth: 1 :local: :backlinks: none .. highlight:: console Package Dependencies -------------------- We currently support *arch*, *debian* and *fedora* for automatic dependencies installation. These are the current dependencies for *Arch*: .. include:: ../dependencies/arch.dependencies These are the current dependencies for *Debian*: .. include:: ../dependencies/debian.dependencies These are the current dependencies for *Fedora*: .. include:: ../dependencies/fedora.dependencies If you want to build the documentation as it is displayed on our website you also need this pip package: .. include:: ../dependencies/pip.dependencies .. note:: Our base support is Ubuntu LTS. i.e., the dependency packages installed in your system should be at least as new as those present in Ubuntu LTS. Recommendations ~~~~~~~~~~~~~~~ If you want to use Qemu, we suggest the following steps: 1. Create a Qemu image; 2. Create a working directory in your host machine at: `mkdir -p ~/p/mount`; 3. After you have your working QEMU image, we recommend you to setup basic stuff (this can vary depending on the distribution you choose - kernel setup, ssh, etc); Install ------- Manual install ~~~~~~~~~~~~~~ In the kw's directory, type:: ./setup.sh -i bash --login This command will install `kw` in `~/.local/`, and append the following lines at the end of your `.bashrc`.:: # kw PATH=$HOME/.local/bin:$PATH # kw source /home/$USER/.local/lib/kw/bash_autocomplete.sh If you use another shell (`ksh`, for example), you will need to manually add the path to `kw` to `PATH` environment variable. To check if the installations was ok, open another terminal and type:: kw help Package install ~~~~~~~~~~~~~~~ - Arch Linux: Available at AUR: https://aur.archlinux.org/packages/kworkflow-git/ Update ------ - Update using `kw self-update`: The `kw self-update` feature allows you to update `kw` without having to clone the project's repository and manually install `kw`. For more information see :ref:`kw-self-update`. - Update manually: You can update `kw` manually by pulling the project's repository and installing `kw` again (`./setup.sh -i` removes legacy files and installs new ones). Remove ------ There's two way to remove kw: soft and hard way. The soft way (recommended method) does not remove ~/.kw files under kw management and you can type:: ./setup.sh --uninstall # or just -u .. warning:: Beware that the following command is dangerous! Use it only if you are entirely aware of what are you doing. We do not recommend it! If you want to remove all files under kw management (e.g., ~/.kw files and data statistic), you can use:: ./setup.sh --completely-remove Global Configuration File ------------------------- All the default configurations adopted by kworflow can be seen at `$XDG_CONFIG_HOME/kw/kworkflow_template.config`; this config file has a comment on each configuration option. Finally, it is essential to highlight that kw loads the default configurations; next, it tries to find a local configuration file (detailed ahead) and overwrites the global options with the ones read from the local config file. In summary, the local config has higher precedence than the global config. Local Configuration File ------------------------ Kw allows you to have a specific set of configuration per project. For example, if you have a particular kernel tree named ‘drm-work’ and want a different configuration from the default you can follow these steps: 1. copy your config file (i.e. `$XDG_CONFIG_HOME/kw/kworkflow.config`) to `/path/to/your/kernel/tree/drm-work/kworkflow.config` .. note:: The default name **must be** `kworkflow.config` 2. Change the options inside as you want. You can also remove settings you do not want to customize; In this case, kw will read them from the global configuration file. 3. Done! Every time you execute any command in the root dir of drm-work the local configuration file will be read. And if the file does not exist, the default settings will be used. kworkflow-0.10/documentation/content/project_structure.rst000066400000000000000000000141471513255534100243350ustar00rootroot00000000000000================= Project Structure ================= .. _project-structure: .. contents:: :depth: 1 :local: :backlinks: none **Kw** is written in Bash, and it follows multiple rules in order to keep the source code organized and manageable. Some of these constraints are enforced by external tools like `shellcheck `_ that helps avoid common Bash mistakes and `shfmt `_ that enforces code-style patterns. Other rules are described in the :ref:`code-style ` documentation. In this sense, this page describes the overall code architecture and some details associated with the code. If you are starting to work with **kw**'s source, you should see it in five different levels: **hub** (`kw` file), **components**, **libraries**, **plugins**, and **documentation**. Some of it is shown in the picture below. .. image:: project_structure.svg :alt: Project structure overview :align: center Let's dissect this diagram and get a closer look at each section. Hub (`kw` file) --------------- **kw** supports multiple features that are not directly related to each other. For example, the `deploy` component is not directly related to the `config manager` feature; nonetheless, we still need to provide a unified experience for the final user. To achieve this goal, **kw** has a file named `kw`, which works as a Hub to all components provided by **kw**. In other words, all commands are managed by the `kw` file first, and this file is responsible for calling the right component. If you want to add a new feature to **kw**, the `kw` file should be your starting point. 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/send_patch.sh` file. Usually, the component file follows this basic structure (see :ref:`code-style ` for more details): .. code-block:: bash # Multi line comment explaining this component. # Not necessarily super detailed, but enough to give the reader an idea # of what is going on. # feature entry point, this is the function called by the 'kw' file function _main() { ... } ... feature implementation ... # this function reads and interprets the arguments function parse__options() { ... } # this function prints a small help text or opens the related man page function _help() { ... } This standardized structure makes the components easier to read and understand, as the top of the file is dedicated to explain the component, and harbors the entry point function that organizes the component's function. Furthermore, the options parser and help functions are located at the bottom of the file, allowing for the middle section to be dedicated to the actual implementation of the components' functionality. If you understand this organization, you can easily find your way around the code by reading the code in the main function. Libraries --------- As the name suggests, those elements work as a library. These files are shared and contain useful code used in multiple areas. For example, we have libraries to help with string manipulation and remote access. Plugins ------- Usually, we want to isolate code that can change externally, is very mutable or too specific in the plugins folder. For example, we have a DRM plugin specific to the kernel's GPU community. Documentation ------------- We have a `documentation` directory dedicated to the project's documentation files. They are used to generate the man pages -- accessible via the terminal using ``kw man `` -- and our `website `_. The content is mostly kept in `.rst` files and is compiled using the `Sphinx `_ tool. Adding a new feature -------------------- Based on the previous explanation, If you want to add a new feature, you just need to follow this template: 1. Create a file with the same name as your feature under the `src/` folder. 2. Add your feature name in the `kw` file, and include your new file as part of it. 3. Implement ``_main()`` function in the file you created in step 1. These next steps relate to Bash and Zsh completions for **kw**. They are necessary to maintain the project updated. For the Bash completions, add your feature to the file `src/bash_autocomplete.sh`. Use the implementations of other features as a guide to create one for your new feature. For the Zsh completions, the steps are a little more complex: 1. In the file `src/_kw`, add a string ``:`` to the `commands` array inside the `_kw` function. 2. Add a function in the `src/_kw` named ``_kw_`` and implement the completions for your feature using the other implementations as a guide. The Zsh completion system is really complex (but powerful), so below are some references to further help you write your own custom Zsh completions. 3. If your feature has a short version, add a line ``_kw_() { _kw_ }`` above the real completion function of the feature. Zsh completions references: * `A short tutorial `_ * `A long tutorial (focus on the section 6.10) `_ * `man page for Zsh completion system `_ Fix a bug or improve a feature ------------------------------ Let's say that you found a bug or you want to expand a **kw** feature; you can find yourself in the code by following this step: 1. In the `kw` file, find the feature name. 2. After identifying the feature name, see which file is included. 3. Take a look at the ``_main()`` to understand the code sequence. If you add/change/remove options for a feature, you also need to update the Bash and Zsh completions for **kw**.kworkflow-0.10/documentation/content/project_structure.svg000066400000000000000000000406541513255534100243260ustar00rootroot00000000000000 image/svg+xml Deploy Build Mail ... Remote kw_string ... kernel install Subsystem ... kw(HUB) Component Libraries Plugins kworkflow-0.10/documentation/content/tests.rst000066400000000000000000000056051513255534100217100ustar00rootroot00000000000000=============== About Tests =============== .. _tests: Kw's tests rely on `shunit2`. The `run_tests.sh` script automatically detects `shunit2` in `$PATH` in case it is installed in your system. Alternatively, you 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 List all available test files:: ./run_tests.sh list Or run individual tests with:: ./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. kworkflow-0.10/documentation/content/tracingandprofiling.rst000066400000000000000000000074501513255534100245720ustar00rootroot00000000000000===================== Tracing and Profiling ===================== .. _tracing-and-profiling: .. contents:: :depth: 1 :local: :backlinks: none .. highlight:: console The `kw` project offers two complimentary functionalities: 1. Production of tracing reports of `kw` executions. 2. Generation of execution profiles using a tracing report for deep analysis. How to produce tracing reports ------------------------------ To produce tracing reports for every `kw` execution, you simply have to install it like this:: ./setup.sh --install --enable-tracing By installing `kw` in this manner, every run of `kw` produces a directory `${XDG_DATA_HOME}/kw/tracing/`, where `` corresponds to the timestamp of when the run started in the format `YYYY-MM-DD_HH-MM-SS`. This directory stores CSV files that form the tracing report. As we can have an execution creating other parallel processes/threads, the aforementioned directory houses a dedicated CSV file for each of these processes/threads following the format `.csv`, with the main one always being `0.csv`. As an example, an execution that spins three other processes/threads, besides the main one, and that started on October 18 2023 at 14:42:34 would produce the following hierarchy:: ${XDG_DATA_HOME}/kw/tracing/2023-10-18_14-42-34 | -- 0.csv | -- 1.csv | -- 2.csv | -- 3.csv What type of tracing report is produced? ---------------------------------------- The objective of the tracing report is to describe the flow of execution considering **only** functions defined inside the `kw` project. Below, is an excerpt of the tracing report of an execution:: entry,include,1697650714354383739 entry,include,1697650714357746065 return,include,1697650714361935150 entry,get_valid_signals,1697650714363833716 return,get_valid_signals,1697650714372559137 return,include,1697650714374769796 By the above, we can see that the execution made a first call to `include`, then (inside the first call) made a second call to `include` and returned, then made a call to `get_valid_signals` and returned, then, finally, returned from the first call of `include`. The numbers at the end of each line are the timestamp of the event in nanoseconds, which allows us to measure the time spent in each stage of the flow of execution. .. note:: `include` and `get_valid_signals` are functions defined inside the `kw` project. How to generate execution profiles ---------------------------------- To generate execution profiles of a tracing report produced by `kw`, use the script `scripts/profiler.sh`, like the following:: ./scripts/profiler.sh (--full|--summary) `` is the path to a tracing report like the one described in the above sections. The `--full` and `--summary` options are the two types of profiles currently supported. The former generates a more visual way to analyze the flow of execution and the latter generates a summary of time spent (in nanoseconds) in each of the functions the execution has passed through. Using the tracing report excerpt shown in the last section, and considering that it is stored in the path `$tracing_report`, running:: ./scripts/profiler.sh --full "$tracing_report" would generate:: --> include 3.362 milliseconds --> include 4.189 milliseconds <-- include 1.898 milliseconds --> get_valid_signals 8.725 milliseconds <-- get_valid_signals 2.210 milliseconds <-- include while running:: ./scripts/profiler.sh --summary "$tracing_report" would generate:: get_valid_signals,8725421 include,11660800 kworkflow-0.10/documentation/dependencies/000077500000000000000000000000001513255534100207625ustar00rootroot00000000000000kworkflow-0.10/documentation/dependencies/arch.dependencies000066400000000000000000000004141513255534100242460ustar00rootroot00000000000000bash git tar pulseaudio libpulse dunst imagemagick graphviz texlive-bin librsvg bzip2 lzip lzop zstd xz bc perl-authen-sasl perl-io-socket-ssl sqlite3 pv rsync ccache python-setuptools dialog curl perl-xml-xpath coreutils b4 procps-ng pciutils libnotify python-sphinx kworkflow-0.10/documentation/dependencies/debian.dependencies000066400000000000000000000004561513255534100245610ustar00rootroot00000000000000git tar python3-docutils pulseaudio-utils dunst sphinx-doc imagemagick graphviz dvipng python3-venv latexmk librsvg2-bin texlive-xetex python3-pip bzip2 lzip xz-utils lzop zstd bc git-email sqlite3 pv rsync ccache dialog curl libxml-xpath-perl coreutils b4 procps pciutils libnotify-bin python3-sphinx kworkflow-0.10/documentation/dependencies/fedora.dependencies000066400000000000000000000003541513255534100245740ustar00rootroot00000000000000git tar pulseaudio-utils dunst graphviz texlive-dvipng latexmk librsvg2 texlive-xetex bzip2 lzip xz lzop zstd bc git-email pv rsync ccache patch sqlite dialog curl perl-XML-XPath coreutils b4 procps-ng pciutils libnotify python3-sphinx kworkflow-0.10/documentation/dependencies/kernel_build/000077500000000000000000000000001513255534100234215ustar00rootroot00000000000000kworkflow-0.10/documentation/dependencies/kernel_build/arch.dependencies000066400000000000000000000001601513255534100267030ustar00rootroot00000000000000make base-devel linux-headers bison flex openssl ncurses pahole xmlto kmod inetutils bc libelf cpio perl tar xz kworkflow-0.10/documentation/dependencies/kernel_build/debian.dependencies000066400000000000000000000002621513255534100272130ustar00rootroot00000000000000libncurses-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 kworkflow-0.10/documentation/dependencies/kernel_build/fedora.dependencies000066400000000000000000000001721513255534100272310ustar00rootroot00000000000000qt3-devel libXi-devel diffutils gcc-c++ ncurses-devel bison flex openssl-devel elfutils-libelf-devel openssl dwarves llvm kworkflow-0.10/documentation/dependencies/pip.dependencies000066400000000000000000000000341513255534100241170ustar00rootroot00000000000000jinja2>=3 sphinx-book-theme kworkflow-0.10/documentation/favicon.ico000066400000000000000000000151761513255534100204670ustar00rootroot00000000000000(( h((P waDDD\D\Q(DDN#R0 aV6DDDDDDDDMѓD3DS/p[;DfDfDfuc1aH6DDDDDDDDDDRDDDU4< D3DDCDDDS/`R/>DDDDDDDDDDfDDDDDD D3DDDDDDN%@)RF DDDDDDDDU2Z8CDDDDD[@jv~DDDDDDDDY9^?CDDW5IpC Dq[8hOeJeJeJeJfNkv{eJeJeJeJeJeJeJdJQ&oR)C\O#D}jyyyyxd\DyyyyyyynTZgP,DDDDDDDDDfDDDDDDEO%L$)E3DDDDDDDDDDfDDDDDDU.BW-QDDDDDDDDDDhGKDDP%\Aah KgDDDDDDDDDDpeN$M F>V4DDDDDDDDDCyFu`T,DDDDDDDKW6c< DDDDDEI_;=U2DDHT1t<D?cC=??{yx?0880??kworkflow-0.10/documentation/index.rst000066400000000000000000000035011513255534100201740ustar00rootroot00000000000000.. image:: kw_logo.png :alt: kw: Inglorious kernel developer workflow tool :align: center :target: https://kworkflow.org kw - Kernel workflow Tool ========================= **kw** has a simple mission: reduce the environment and setup overhead of developing for Linux. **kw** is composed of different software components unified in a single interface. After installation, ``kw`` commands become available in the command line interface. The kw project is available at `GitHub `_, and we also have a blog post which can be accessed at `here `_. For more information, check: .. toctree:: :maxdepth: 1 content/installanduninstall content/howtocontribute content/tests content/codingstyle content/developmentworkflow content/tracingandprofiling content/awesome_kw Kw code doc =========== Check out our code documentation. .. toctree:: :maxdepth: 1 :caption: Code documentation: content/project_structure kw Tutorials ============ Check out our tutorials to see how you can use kw. .. toctree:: :maxdepth: 1 :caption: Tutorials: tutorials/setup tutorials/manipulating-kw-config-file tutorials/buildlinux tutorials/cross-compilation tutorials/kernel-config-manager tutorials/deploy-kernel tutorials/rpi-deploy-kernel tutorials/kw-env tutorials/codestyle tutorials/find-maintainers tutorials/kernel-debug tutorials/pomodoro-report kw Man ====== If you want to see kw man page, you can take a look at link below (The HTML renderings of the man pages), or you can install kw and run the command ``kw man``. .. toctree:: :maxdepth: 1 :caption: Manual: man/kw .. toctree:: :glob: :maxdepth: 1 :hidden: man/features/* Indices and Tables ================== * :ref:`search` kworkflow-0.10/documentation/kw_logo.png000066400000000000000000000640041513255534100205070ustar00rootroot00000000000000PNG  IHDRK26sBIT|d pHYs *tEXtSoftwarewww.inkscape.org< IDATxwxTL:${Gt4(4A(PTk"bNJ" RH齉K _Hr^g&yxIr޳kZ~:B谨5#+ZYK """""""""1¦},!5H,Jd?Wh3mPk$$""""""""Jct$3D6O.Z,x=SnKkvDDDDDDDDDJJb\?0JYղhTckȏ_F{'_䋂 W\|ŗQO 0$$""""""""JcI7y{kFhngyӉq,VB4/Zg5{~֨H8 IDDDDDDDD/^9ʋ7,?6?~"+MDDDDDDDDyQ}^/\<ϦFX,:fj>oR Q wIdv7oYܶM~{mGDDDDDDDDU$8ꬎ@)fJ=q̂3[}_|q_q(0JDseV1/5wl V>7*Gв2++fJwzÄ_촶_ZvA|ٌ+n?IlYj wb˥!""""""""0.idT2%x_3]Ndi9TJ:섺֌0j}ru  aS\ɸ!LDo7Aҗ"""""""""} (K'K:ODS@yX{7KCDDDDDDDD3}w)AdaW/kV?#S HΉ!OJ'-Ɏ:%[n7gZQZ:/"""""""" :!.$Ĭ<}xolq~g:IDDDDDDDD9s@veVVR̔zjyEg޿u=k΋|EN&Ӊq??8\oiftRDDDDDDDD^>S̜ c;Ųxc0 ÔΉcii&I%Ȍ-gu~Yg W:/H?wtd2R]A'/3]?{JCDDDDDDDDYUs]=sd2 #P>50d霈[̪1/ QPՙO<2-KCDDDDDDDDN3$qK V>7U{Ή(U!XD*1x?uYuΉ(U@YɄs-[_:"""""""b` BDDDDDDDDYbLƟLO:"""""""@o10Pn5Ҏ Ԙrh؊쨻`έ%Qqp6Qbjrq||ص֯;KDDDDDDDD(+fǕY1aF|k;Vw_yY!X̲+.R,yo}/&?U&4Y6JHM֧> ybVUX 4#vxe?imUo)DDDDDDDDզdL\"ċ7xdɻfrKWk,>ᕻ~9tNDDDDDDDD2â2+, X⑾/mbI9yn'=L=$""""""" T !e#H [dž ۧ#f˧ڽ{B3pQ#_]TGl""""""""IY*pa\q扪=a'few4N߮A{ut#_o.᤽skODDDDDDDS=sKNnz鰍8Un3ȭ^MI# e*{f9%S14Ͱim$rO Yi Zפ Z߶3irWs!"""""""D#g|d&pyjBVvNm?^MIbGnIZStضX#n#%"""""""e1/]zv8 'vz~Y uJd9*Ś·S@|u'$VkMk릻)|vR=}qKJpI$,f+;2\g{!+ջmUOV\"'1v 촶ןuTtRDDDDDDDDɲU!݉8 't~]k Yicè8eVz8{u~C>J_DDDDDDDDɲըhJ*VxYϊ~ HN(biFČv$՝n: YiK[?`H-՝:fDW ]Yk&^h3$ YiaA!o*|Va8=*5':LF'BV,hp]Yf&=]b|(Ȳ< MP!;mzƇSfjs9QɶgւؿYz):5jt.ywz#Nz5%t. 2Uv*|THCDDDDDDD!biaK1S LPJ3v^ɴ*ҹXX!_uϔ·[,a1\/1*8>feZ~4lnEbjRTBJRd3Х i +C~ha$IHDDDDDDD'bV_/8v]]$|^j?vCUDƲ+M>]klc[:&6+sV:?"""""""9j s\!T!y~wMGUg77|Aj?ybrCDDDDDDDʱ!qz>^!y>n#O=';?(aՈ,?Ѫ>Rj܈ȹ\9}rT},|㛇S Zi<;~-Kba_?i织l?75c6uH&({2%"""""""'˱g 7+应g/*1+?z=i+2wEV 4 -?mǛG۝O4K=󙞫꼾?wԦgIDDDDDDDNk1+*$D9n 4`\Ҙi\24Pjj.Oח|ztNDDDDDDDOŬ"QٞhoQ8VZ~z+ Y^0ar枷v8Ĭ+_iLDDDDDDD-7ãbeVk-Z,dYu"\;PxVǍ֍y40餈trtα:rfK܁u44 #Ygls>R/Ϋ3Ȓ;zm蘇ގ)Xt^5@g1?0YsL"""_0OsD4$ߕP@9 6 B>"iTŬ5Mq?(hG|?Y1lnZ/}k߻K5=(ÔPsR*˫hUtlUĊ(CI(ZjQ`WԔh 餳e|38,MR.9iS[߼pܧvyW֛"""""+_"" reFR~Wx4hK܁ =iAvP!h!+`H1*|ڡt)?zg۟@/Bm`Z޽׿_wFScQ *` `!j/$H\:v'#e}=,zi1 #k!k@+tJK}rI#jZ`;>yJWz)4Mt~GjaT35jC8{_{}r/1<uM#닃\HT6]ɏUwndߜf̈́]/5%X}vguz6ROBUlsbo ZyU$$a7t{,6}~o'_0+[wNuc6qIt\DDD( @PMIFc4NC=`Md$cQmn_m>A<ҳu5imZHiĘ-Y[V$Exǧoy'c9YDDDc1+0<]X;@(Oɵg H}cCy,|_zhBVRMXu(d@1g79obuÆ^Zb]?Xn˞8iuz'e+4Y""sDYpOF#koMtXzi,y:5׭achUUW϶wgu]9høL!""""ۄ ; GQ2\9d{ģֵYWޑ YU~[G3ƒV=S&";cw*| |Vh}zyEo DDDDh.tNDDDDtDD;+B򇄋wuic+JBDDDD,Y#X:@V$V%΃V:  `' .[}z""byb".GKwp}}/" QP0~,7`DD,ʥԫŤ+IN?&WFt"DDDDD ^'B{fW&\e!4Ͱհpix<PO(6]BX"\LR~o*;$&K1Y<_ ^(6Qb1wID\wDGlWޕJWs!"""7yqY5gvy?L.)/+z6|R:jdOM?o)`ѠKOmya5R9y?\0xB FV]+J9_םMixX9=z^9sU9׹ KֺDݥ-5Ӛ|4>=k˟.oݝ'^/>zߝ?8fץ^-o'_0?K+[Uͨ Q^cjc0.+Te ߣ{:4]÷|=x9:#RsUwsջ-tkLt iȕwAAm>Pa\|4 @1xKsL"_J( bP 3 2} Q/@-D(j(e׮U4+t~vtj `N1O(9\(!PkiJ85 QcDeʬ@R(4ơ52fe=0ɣlic+ Ndi'S2ats>XWWjEײ?kSϛ?_uSܾzfv).Rms V{@!IB~?&VtK*n!ݟLb@c1*>&-",T\RPcLb~`XGgA2sir&.r0|agk?+.RMqj,uŬY'trxɇB-|xd|ZҹOh+upM(~zStg4 k;pxLWp7Ԅ!Pܙ V`.6S$c&k WVqTM?@Q| 2v$#1w"UƳvP+lg@JFPc\d=t[xids }EwibV:7D1VBzÿcrԤV] 2\'٭JB>` }s_,YIڎYA_: [c5/fހv;eI;_VlJ"E|9f<+fM IDAT`(j,;*C<ԛtՅk_!O`1KPYjvrϛPۣBDc1^v5MxEO3t&<M_o*=e=G\5lt̀ߥs!T܏W -֔Ki 1Wό'xIu8 `ִpь߽P_ByuA_$Q(~R@.A~eN8N,AFЩc ukaNl%ꏷd=Ǫ:gJB>Uҹ)+'y'^0fH<jjbVme7n*Bs/mVj/;ÕY`pZ8"@oX0 jUP 'C͍FVU(ICgnYвxuBZQm!O0`\]<5E:S Yo NSzWT0 qko[cTڢ N 3( w?a)sV`3Ԫ,]XP+)%:E8PABP+g^ BпIVK_7~3D' YL==߫GRk]w"ܬ)VV9eUV. 8(_c/s$j,fl4s9 } l:*Zi!,HޯS~n @R N6=RPY1ŋ}<ұt?6{yt" Po Y撺 59\usB?Pǂ?w2P~PZ8#,,9FpUZ!?jeV¹k,xsꉔ3aI\3&lSᘙy Y ? = ꔛ@ՋHϭ(Tq]R!sZcH^pˠ~{S/:qm`,e-ȯZ5yPj r%%J{5Ο-;NjYOq[JwL]Z/h yOB/'^A[[UFњbՁFMoIf5K2uG.0 p-\P ; 瑗N6ԶOI']Qfxy'bT;d3PKS{eMCth=ZKG7f 2\C\q˖fp T0 /Rc4*\U}0z! 9@5*}Y.,]*Zd@2KC,ːh=b#=-M~VtMPnl;O thfpw:Qt"r;K[qEcl?6b#ŸvXYQK-xJea\+:.EbsfrQ(ZO  p9rjP_Am;ZcCvbVZL,M{W_!o߽N-8$S< upe{Lbo,]VdIujPߔ}1&j#5Q:fa:ѥ\.t>t,dI2 #%,(XJF|% d9 uêB}VڮK"O0#XI#6Ww'H'Yʻ/d,d&P7X^46`ݽq b܂;bVxPu;w 'F9RKhJ\P:5XXDy-m'Bݡ,hs W"1u5ԶV]:Qu)/o, +0׶ u?*?л sZRP'줳7WzaOP}tًtŋY.È{f/衽4&r¡k'uP Mb5&v9[ =XDu6ѕ6@y$2@T&,SVoP=Vhݠ1c}@P;"Z|['^̺dq+VD앳SSW\|'4}%΅V? YGlhK%neLS3LZj4y5N#Rj^UR:?T k1ieu?濢 \!G޸qs0Mt^e'~%5XBjraL|RV2a3UMqIR,ۦ}?ZIՀ$ YB《-NAӡT;z1Հ[zW,?o^2Oz3?-e~{ s vIvP=mP=tp?6\ =ԁjybnzMh1Ƃ7'_czkJX2M3${g'aVը)Msgu1΄’ֻ+No >Q s=fCkvuHTMBdAd tTaB=@cǛnUYl`õqcPw._AMN 璗N(dzJ0"h 3ikmz@-|cu%wdcõ翢{g|ËC]tuꔶgХ5tųSR7鈱vmӬ[}0Zd}N+Î7G 9WJ([ %X+V6]7;v(=c57%] [: 5X"y>YG%7:;-f -|5c񉗵z5%4ٱkna\~ :b ;o6t={w9VU]C-P`Jyni+t9`1ށn$P>]l -ԝP}3ˀyJ0CPs J8dxegϠ 5ՁAqn Nˠ2翞/+euD:łO80km3Ν^}1ʍv%_PJEɺ{ 2\'}YiR j] C-7׻1u ^2^[i,Je16ZOǜZ_3M7&yA xB0=Ṕ(MQK' CpזPҬkԿs>j1 >PY%.0^,֯'9&լ&M;gv\[xizegwk?ЎH7RT7⧷Yn@ݡl5[Yx-wع o[x_|u^0[MCsR"T ԤNc`V9zݼÎC[(ӆCx~Yw1cVls+ol"+fjՏ^8 < k#eV_xѓʴUG> O%U9v-ɩ)Vѩ[ϗi0 %|7a[y]ʚ0U0zZU\(~20Zl ]ZbXi kY/-tiӠ~ޭ:y,TQk*XvJ^j2+mX \x+Ԫs| {YP}[ bE A ٻee dq{FC1wk4$է ]6 P+|g@J̢zaoB^a1ԉX]rb#濖^ <|c?@4Ϟ-8bzRrBu;W%6>غp}Ka[>go?KNM=xIW{G . yF,BU%Po|u9l59SVf*-V]>nykk웸*->gUz UxzuP@j>0/:YA~%lUzD[ʘoJE+BaBzj[]|rjݡKԪ, U鈱na蚟;/Ŷm/1M3G=;0 r ms!Ն슬xN{y .`$?טGfYu6M3}sosq[TvF$v+oo~ ;u [:¼V(;tuE('-NcUN:[ vS;!eECcf~.Bh:+&A!PKDN#z@W]x,Bξ:ov3nʢ+@~[- -Zh1RMK|'[.ǻ54l݇7:x o%m^'yM7]mBrk]8,@C 㮍P+mM*+jo91< `(XVZ!Kr (mN&@ynz>ŖI͙q>,0RT=h03 G..\RG|$}&7t"䵺P,;^ %=V>F`ˁ>jߋ@osY;Lvڹ zadl4Z(_P+R$xjt*5oV ( ]>\C7Az !kaxB(~'-RK;IBm 'r͙QPN>ڋN!>\1pkychߊ}1 G[N(fP#쌇bX.BoӈaQt"5Br.b.-[1o>m^S̺ `Mn @zk>rX:8%w@\Bm/$|oP͝OL#MQ"cNBV7%fR̲fn)],^KW1+_o3LS`9#28bk1}u=U﮻sh^I [3T:t!k.Ԋ,+d:=VxˠV%7-}=&Zw CzC*Tc`h0rP'EԪ !*+M2T.Vo`p5z{ꙕ(f)WFgھZB\Y"5Xz`0x?5K~Zoa퀖_zKPӢ<.X5[ŗ=n;7x휜*,;w:LOu2ԶDŽh$[r (P3 AAXW3Z9m`vGw: bV'sI|u׭9V)g Wn>Bߪ`!"B? zOܗTsXmk5$vV,_%>0 7_=u;-PYI^NOPBO Dސz-=`PlZ$Φ:R.8c5QtwoCޝǎ6ݮIP0!%Ixt4נp_cB?0x*=So@Klz5\MX[»#uV١T N[q?\N< S} n7g6<c;u]qZ»VϦZ»:)IQ2S\]ajǎ{q}gnvKNMѹ\h)fE Ot5 {`tƻx-L묒~]kYaa|w, yp*Y b_`ㅏ *d#(,۩D1Ԫ6\4P;=tvkegy_c@o1/9rl;yjEW/7'[5ZB[H?PV! Pw cQ\sʞaf/mmvNž -%7+zMd!xkcgGj<J6^[1Ԗ3 Kn" tP[4 a}JRºe-[T@EF).6^;'-cWmpu;V:"/Ig]Mo<__ݜڇ_7ÍJnTnG b֦J琝ba25k[}ng}4=ErYp藕<-^\[Y;7vx6^;'N\!W bo ۖ 9<|QQ(>8poBiϖCIi:YWYicuW f.95٪z.AoAX+W/cV.久Co,@Jɖ`VR1+vCp ",3Gvgw YŦzX;Ŭ6w1JtyM*R (\,I,O9gn*57|aώ2+Fmo!}uʰUDvxYg:.Vu ? :T]ܞu1kgPI+ WHwɿpjŬp'cnCh91V [+b~Y!P'3J8%F ŵ6(WJh r-ECoœDعMhc PC!j1Yf:Ƴk>XA}1s*XYYsUP˜h7Ŭi?LJ I5S⓯z?`HWj3,P/oI'bP97;m ԢxˠgbuZY])#YY-VfNRBXCꆀ3tg:P9 E!BbſsAuzqeq<ˋYOou֥ J%]u MVI"aQ6p`>- @  }' `j׵N5B ?q]C )`H˶pr^U7"$71Tn:Ƴ(!9tTu5- 9tX^w8Bmސ=˷/ LNfW֚5G,+swz,bV(q;W4ȎoL NuU:HMfí+9HYf:3_O 5%VZx?iL&|Aa;ߎy{JwIBTc@07[f{zYCpJ&҉yI5Tn:-?+efosd_ %]+d;䒄Dz#]WocIjeVDloNXq۪d`SwVMx"q]R$WYIG .P=TԘL*7]oQX5V8 `֭.v69M[m˷VWbV_.øbHZaLEaQAABv_S $i8d<}i_i|5!5Q/m"CwSOT ݂Lz.-R?iYt6Oo))fe,f@ҨePh$9y+TnR".HP\,ZY0ujki㺞TW<٪BNa\zΣ E\|?YV\(O 0@DlsuV Mx6{jnKu81VzC*7QV v P@;,Yf:feEI~nn V@E cƫ2ǎeWFdVx~yx+otݟ9euyA`^@ 5u웕UO0w"㑭&5V[j 7$C;/5" ux[bBӊAyd/;V[( &-ŬKNRM3+J`/lc0Wȁ1}{<[F\1D80yvBʎ dxL_VCZ@iZYtmw}2@n_E(nn*æy %gJ[%}C.1SO"wItxvPct̸: x6 7*[+ u'[&mMc㺞xeQu LƮ(Ə߁kaпGs5% 9~!/Rk!#Ka^y 5΅)@_VruT>h ``VZXv|kA\Y!sk ʢ#}$u8i^ r:QN ji n gXcXƂT4dQP;L ,;U*u*G.\Gb9pVP#8v ^j\t:;."̅FV0\Փ#2s5T]~$ 7o,Wg4?l+]"'1R vN"5][sP'XDS3 n0X16P.^/m [TpAMl>[[Wosڽ(`d`Y(CB%րE=ZYtMw\&f;Ԫ mf0&^O(Ϙ ?J/[`PK i O/v_jKj,++ݪ׋Xske5s@_l`T$4iw\&c/У[uX:vppV8XH⌼ٞPw26~YpJ jg!nU/ܖOI@%VׂWIx翾|mF-3O;EY]AǞѵ/΅im~҇Fxp=XۗVP' Xx͜?=q,妻`@LzL0R: LB7 (/gMoklbVBumr`#+7vGt7-ru\8bBWKoyw홅,V\jQ*dkr1[%^IbA cQP7$ 3T.Lm_༦XաNevX7/ڮi}mŬvm ,:LNzcҹP@UВ>ѫ$+|pf|̶^n}W˾xOқߤx+[jJb0n7<>ޖ뿚I+>c/ ,a}/i2EA#YYm-8n9IdwBnՠqNL jyZϗE׉e+dۻPIepg7N45a݂j D˔R+6%2oηZ/ _uj,i\-rۭ@{]qǑtl wX4׮r_4ZRI/!wqEhyi)[ C{(/MK~vV"X1pHd7UF%L'?&J[[d[>/w*8}\8@[\ ޑ@n7rŒI]rUX bxUYNjr[j{G>ۆwu պKܶy_nNFnQXGkJ/p- _Jqr I@v 9\7Ly2ɢWQ A';ֱ۰^n $Mtul{ *_a˄Yec[~(H>o܃u&_A <%$-đ\e`I0:IgIjg kcH=|"?n *َMDLΖuX|edeY>lg\\@&?jZ/u;Ieցd%=lrޭBRVCV-B̑tu;a\Uru¼`ɬ 6' XP"VpXY`K$-3@$ Gp3|FAT|gJgNW4[As+.?nB.iQ)rn;!1VlV4j<"OfIRY^1,$`؎ǟsGj POUh-DɒVL;RYvB^>|bo>; [@HD5kr"grr!|I徆|IQZX~Zٚ翱U,ɬCu]8>YDhe[!WN NוqKɝk:7>T[4lrƣrF>Tj6y`jy?揱$:lvY/Ī1ek!r*|Cz:-x*yI&ښɒȿH:Pқց;-QƱZ=u9Vf2IIfG}1dK2MiieQ*8WȺZ\'Iv_< zZxVIZlG.Wu @-tR)|@3-BVnku !|37L@"V$ntu.t} ֧R뗔=[^V\V.aM2+mVZLҡnUVҒntx/{shlɬ& JIf,Ī1{[ >XXRUQ57da ^qMn;kI?jq,@>W @$UȽg9E}H88TIKiKT|.{rIJD6-յ¸u X9bx\XIT(^/i$R^)Z'WAcmŒlI$B~ uZ>l"9Bm$_eNdSI+ctq E 1IҳQ]]/QrslP#}-uxoy5^.J(P1`/WX4P~Rr}cb3ҕT%׌>n>澔IIHO{}m8uD/%uKGҼԿ$$?*{' owcP|gwt\:;!W+"Ɩ `cI^$TN4p̔Zxlr'Y N991*ʦ}쫢uݎ"]^tQ-_I_R?}iDr}Y\OR@6_(oVF}ΐZe@Kzmi"M$5h9f.pYGM>X1,inchV(yNv[FHIeFo4hl_[ V%Y% ^d4 uG=r[kZR^<^m|<^6ͧJʓtܽ= \rg}'s{}sMK:K'þŃ(/=sgV8v Y9qϺGcv;=rF0FѹrUs?|8 {YwT4$v^rFY]J.YC@" Wl^]/\EH-5\JjUrAM?O/\nKڒZ{.տ.*{&/kR\e I_mUXTҷ6bzdOuqArBE3tOXk2+N7[ߥ7U5sl _L&,kb;P X0Uȉ R^Id\k2K|R ;y^#BɬVM=f6H%&u:rr׳N'v/iCeV-IֱX=uT=f&Kɥ6D@̧JR:.H=wiUqcgKd=YX|{eV =nI%?2TY߉=%I.7Sŗt>ԫ99X|bj_FmO-b']cI2k.?`O}t#OtcUJR:n|ݺ]IDAT%b|&|Ӈ_yX|fRŜh(I*L@" `LYԨ' ޞmvu,,<,Yũg*i @0Kfuh#vc 'v0:Lb:EƶT*{Ssu,,uJL(j| eyEso1~D@}%MVYfe/IOkwLN d$DbiYwv;o mzl @&3Mf5/dVw:LgjW'.l<]y[LYͻdݎHBmïA:kwɬ;,*N,R*iµY8~MkNݵkÊ Lf)jZdV2HVQ>Œ Lfjy~]]~qʰzNx `d֘v} Ϳ)+7AW}Q[^&54蝝 ?;e\e2KZ7ycg^e>[ֶϒc-oY]JwJߴo!{hu,AɬSw=b6ۓz͜> `SqN`DvO3}ݽ.UlmeVZ4~e+H6xR'M&$i&g|f㢣'3_1[䧯h>m~/t:T/8wIENDB`kworkflow-0.10/documentation/man/000077500000000000000000000000001513255534100171075ustar00rootroot00000000000000kworkflow-0.10/documentation/man/features/000077500000000000000000000000001513255534100207255ustar00rootroot00000000000000kworkflow-0.10/documentation/man/features/kw-backup.rst000066400000000000000000000032251513255534100233450ustar00rootroot00000000000000============================================= kw-backup - Save and restore kw internal data ============================================= .. _backup-doc: SYNOPSIS ======== | *kw* *backup* [] | *kw* *backup* (-r | \--restore) [(-f | \--force)] | *kw* *backup* (\--verbose) DESCRIPTION =========== If you provide a path, a tar.gz file will be generated and stored in **, containing all the data found in the **KW_DATA_DIR** folder. If no path is provided, then the backup will be stored in the current directory. OPTIONS ======= -r, \--restore : This option allows you to recover all the data from kw, by extracting a tar.gz file located in ** and storing it back again in the **KW_DATA_DIR** folder. If files with the same name are found during the restoration process, then it will by default ask you on how to proceed. To simply replace all files from **KW_DATA_DIR** with the backup, you may use the `\--force` option. \--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. EXAMPLES ======== To generate a backup file in your current directory, run:: kw backup You can also specify the directory to save the backup. Let's say you want to save it into /documents/backup, then run:: kw backup /documents/backup 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 kworkflow-0.10/documentation/man/features/kw-bd.rst000066400000000000000000000015371513255534100224710ustar00rootroot00000000000000====================================== 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. It is crucial to highlight that kw bd supports the following deploy options: * \--remote : * \--local * -r, \--reboot * \--no-reboot * -m, \--modules * -f, \--force * -p, \--create-package * \--verbose * -n, \--boot-into-new-kernel-once See the 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 --reboot kworkflow-0.10/documentation/man/features/kw-build.rst000066400000000000000000000143631513255534100232040ustar00rootroot00000000000000======================= kw-build - Build kernel ======================= .. _build-doc: SYNOPSIS ======== | *kw* (*b* | *build*) [(-i | \--info)] [\--alert=(s | v | (sv | vs) | n)] | *kw* (*b* | *build*) [(-n | \--menu)] [\--alert=(s | v | (sv | vs) | n)] | *kw* (*b* | *build*) [(-d | \--doc)] [\--alert=(s | v | (sv | vs) | n)] | *kw* (*b* | *build*) [\--ccache] [\--alert=(s | v | (sv | vs) | n)] | *kw* (*b* | *build*) [(-S | \--cpu-scaling)] [\--alert=(s | v | (sv | vs) | n)] | *kw* (*b* | *build*) [(-w | \--warnings)] [warning-levels] [\--alert=(s | v | (sv | vs) | n)] | *kw* (*b* | *build*) [(-s | \--save-log-to)] [\--alert=(s | v | (sv | vs) | n)] | *kw* (*b* | *build*) [\--llvm] [\--alert=(s | v | (sv | vs) | n)] | *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 =========== If users invoke this option without parameters, *kw* will look at the local Makefile and, based on that, start to build the project. This option tries to take advantage of your hardware by using the ``-j`` option with the appropriate parameter. This command can be used in conjunction with :ref:`deploy` by invoking ``kw bd``. .. note:: This command must be run inside of a kernel tree. OPTIONS ======= -i, \--info: The info option, makes so the build information such as the kernel release name and the total number of modules compiled will be displayed. -n, \--menu: The menu option invokes the kernel menuconfig. Notice that the default menu 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. -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 **build.config** file. -S, \--cpu-scaling: The cpu-scaling option lets the user set whichever CPU usage they want from their CPU, basically setting the ``-j`` flag accordingly. \--ccache: This option allows the user to enable ``ccache`` usage during compilation tasks, which should improve compile times in subsequent compilations. If you want, you can set this option in the build.config file. -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`. Please check the kernel's ``make help`` for more info. -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** file via `log_path` option. \--llvm: This option can be set to enable the usage of the LLVM toolchain during compilation/linking tasks. You can enable it by default via `use_llvm` option in the `build.config` file. -c, \--clean: The clean option removes files generated by the kernel build system but keeps the kernel configuration. This option considers whether the user is using or not kw env. -f, \--full-cleanup: Under the hood, this command runs `make distclean`, resetting the built environment to its initial/default state. In other words, it will remove files generated by the build process, including configuration files and script output. This option also considers whether or not the user is using kw env. \--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. \--cflags: This function provides a flexible way to pass CFLAGS when compiling a custom kernel, allowing you to customize and tune the build process to your specific needs. This is especially useful for optimizing performance and controlling generated kernel behavior. \--alert=(s | v | (sv | vs) | n): Defines the alert behaviour upon the command completion. | **s** enables sound notification. | **v** enables visual notification. | **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 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:: cd kw bd If you want that kw become more verbose about the compilation warning, you can use:: kw build --warnings=1 Let's say that you are doing something else and don't want that your CPU cores to be super busy during the compilation; you can tell kw how much of the CPU utilization you are willing to give for the kernel compilation:: kw b --cpu-scaling=50 If you like to use ccache to build your kernel, you can use:: kw b --ccache If you want to ensure that your change does not add any relevant warning, you can use:: kw b --warnings If you want to see other warning levels, you can change the log level by using:: kw b --warnings 2 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 If you want to use llvm:: kw b --llvm If you want to clean your kernel:: kw b --clean If you want to reset the kernel tree to its default, `all config and script output will be removed`:: kw b --full-cleanup If you want to use cflags:: 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 kworkflow-0.10/documentation/man/features/kw-codestyle.rst000066400000000000000000000023321513255534100240710ustar00rootroot00000000000000================================= kw-codestyle - Checkpatch wrapper ================================= .. _codestyle-doc: SYNOPSIS ======== | *kw* (*c* | *codestyle*) | *kw* (*c* | *codestyle*) [ | | ] | *kw* (*c* | *codestyle*) [\--verbose] [ | | ] DESCRIPTION =========== The **checkpatch** tool is one of the most fabulous scripts provided by the Linux Kernel to help developers follow the code style adopted by the project. This command is a wrapper for **checkpatch**, with the goal of simplifying the use of this tool; notice that you can specify a single file, an entire directory, or a single patch. 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 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:: cd kw c drivers/iio/dummy/ kw c drivers/iio/dummy/iio_simple_dummy.c kworkflow-0.10/documentation/man/features/kw-config.rst000066400000000000000000000035341513255534100233500ustar00rootroot00000000000000========================================= kw-config - Manage kw configuration files ========================================= .. _config-doc: SYNOPSIS ======== | *kw* (*g* | *config*) | *kw* (*g* | *config*) [\--verbose] [(-g | \--global)] | *kw* (*g* | *config*) [\--verbose] [(-l | \--local)] | *kw* (*g* | *config*) (-s | \--show) []... DESCRIPTION =========== The `kw config` feature is an interface to manipulate the configuration files used by kw. This option provides a local and global reference, and it follows the following syntax to identify the target configuration:: . You can also use `kw config` to show all or some of the current configurations displayed in a similar fashion to the `git config --list` command:: kw (g | config) [(-s | \--show)] # show all configurations kw (g | config) (-s | \--show) ... # show configurations of target(s) OPTIONS ======= -g, \--global: Set the `` to the global configuration. -l, \--local: This is the default option, and it sets `` to the local configuration. -s, \--show: Display current configurations. \--verbose: Display commands executed under the hood. EXAMPLES ======== Suppose that you want to enable llvm compilation for your local kernel; you can use:: cd kw config build.use_llvm yes Let's say you want to enable the visual and sonorous alert (vs). You can use:: kw config notification.alert vs If you want to display all configurations you could use:: kw config If you want to display deploy configurations you could use:: kw config -s deploy In case of any issue, you can try to enable the verbose option:: kw config --verbose notification.alert vs kworkflow-0.10/documentation/man/features/kw-debug.rst000066400000000000000000000164441513255534100231750ustar00rootroot00000000000000======================= kw-debug - Kernel debug ======================= .. _debug-doc: SYNOPSIS ======== | *kw* *debug* [(-e | \--event) [(-d | \--disable)] [(-k | \--history)] [(-f | \--follow)] ] | *kw* *debug* [(-t | \--ftrace)] | *kw* *debug* [(-g | \--dmesg) [(-f | \--follow)] [(-c | \--cmd) "COMMAND"] ] | *kw* *debug* [(-l | \--list)[=( | )]] [(-e | \--event)] | *kw* *debug* [\--reset] | *kw* *debug* [(-h | \--help)] | *kw* *debug* [(\--verbose)] DESCRIPTION =========== Linux kernel provides multiple mechanisms for debugging; in particular, kw tries to simplify the debug process for three of them: events, ftrace, and dmesg. All the debug options intend to support remote and local targets. EVENTS TRACE ------------ In order to take advantage of the event feature wrapped inside kw, it is necessary to follow the small syntax described below: **event[:[,,...]][;event...]** Let's detail the above syntax step-by-step: * *event*: It should be an event available in the kernel, e.g., */sys/kernel/debug/tracing/events/amdgpu_dm*. If you don't know what kind of events you have available for your debug task, you can use the list option. Notice that users can specify multiple events by separating them with ';'. * *specific-event*: Inside each event (informed via event), users can specify which specific event they want to check. For example, inside *amdgpu_dm* we have *amdgpu_dm_dc_clocks_state*, which can be translated to "amdgpu_dm:amdgpu_dm_dc_clocks_state". * *filter*: Usually, each event supports filters and users can specify it via kw debug by using the filter syntax. For example: *amdgpu_dm:amdgpu_dm_dce_clocks_state[sclk_khz > 0]*. Notice that users have a flexible way of defining the events they want to trace by using the event syntax. Additionally, the debug option provides other features that simplify the work with debug data from Linux Kernel. FTRACE TRACE ------------ The kernel provides a feature named ftrace that enables developers to have a high-level view of the code execution. Kw wraps this feature under the `\--ftrace` option. If the user does not provide any output, kw will display all available ftrace options. The ftrace debug feature provides different trace algorithms (you can see all options by using the `\--list` option) and simplifies the output. The `\--ftrace` option wraps these two configurations by using the following syntax: **ftrace_type[:filter[,filter, ...]]** Let's take a close look at the above syntax: * *ftrace_type*: Use this option to indicate the ftrace algorithm that you want to use. * *filter*: Ftrace allows users to filter its output. This option sets specific function names or even a pattern filtered by ftrace; notice that you can pass multiple filters separated by commas. DMESG LOG --------- Dmesg log is vital for debugging issues in the Linux kernel, and kw debug provides the \--dmesg option to help developers quickly collect this information. Notice that this feature work in the local and remote context. LIST ---- There are multiple debug options available under ftrace and event. For this reason, kw debug provides the list feature responsible for showing the available options. If you use `\--list` with no parameters, kw will show all ftrace algorithms and events options; you can provide the specific debug option by using ftrace or event. In particular, if you want to list details about a particular event, you can use `event:TARGET_EVENT`. RESET ----- When users cancel some of the debug operations, we might have a situation where we accidentally leave some configurations set, which may cause problems when trying to use the debug option a second time. In particular, it is common to have a hung process in the trace_pipe file. The option `\--reset` is responsible for resetting and killing any debug option process. OPTIONS ======= -d, \--disable: Disable all events specified inside `\--event ""` and `\--ftrace`. This feature does not apply to `\--dmesg` option. -l, \--list[=( | )]: If used together with the event option, it will list all available events. If a specific event is informed via *\--events ""*, this option will only list specific events related to the "". This feature does not apply to \--dmesg option. -k, \--history: Create a debug directory that keeps track of all debugs made by the users. It creates a directory and organizes it based on an ID and date. -f, \--follow: Real time output. -c, \--cmd: If this parameter is used combined with `\--event` or `\--ftrace`, the following sequence will happen: (1) Enable specific trace, (2) collect trace in background, (3) run the command, (4) disable traces. When used with `\--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 ======== For this set of examples, let's suppose that you are debugging the AMD GPU driver. You can start by trying to learn the options available to you via:: kw debug --list The above command will show all debug options available in the target kernel. Now that you can see all the available options let's suppose that you have the amdgpu driver; you can list its specific events by using:: kw debug --list --event "amdgpu_dm" You can also use:: kw debug --list="ftrace" kw debug --list="events:amdgpu_dm" Now that you found all the trace options available for your target driver, you can enable that event trace and follow it in real-time by using something like this:: kw debug --event "amdgpu_dm:amdgpu_dm_atomic_update_cursor" --follow If you want to save the trace output in a log file, you can use the flag *\--history*:: kw debug --event "amdgpu_dm:amdgpu_dm_atomic_update_cursor" --follow --history If you interrupt the above command with Ctrl + C, kw will disable the target event in the target machine. In other words, something similar to the below command will be executed:: kw debug --event "amdgpu_dm" --disable Another powerful debug trick is the *\--cmd* option that makes kw enable the target trace, execute a specific command, disable the trace at the end, and bring the log to the host machine:: kw debug --event "amdgpu_dm:amdgpu_dm_dce_clocks_state[sclk_khz > 0]" --cmd "DO SOMETHING" If you want to see the dmesg log from the target machine, you can use:: kw debug --dmesg For keeping following the dmesg log and save it locally, you can use:: kw debug --dmesg --follow --history Let's say that you want to run a command in a remote machine and collect the dmesg log after the command execution, you can use:: kw debug --dmesg --cmd "/home/user/specific_app" Suppose that you have an AMD and you want to track the display manager's behavior. You can use the below command to achieve this goal:: kw debug --ftrace="function_graph:amdgpu_dm*" --follow --history If you want to run a command and capture the ftrace, you can use:: kw debug --ftrace="function_graph:amdgpu_dm_*" --cmd="/root/igt-build/tests/kms_atomic --run-subtest test-only" --history Reset the debug option to its default:: kw debug --reset kworkflow-0.10/documentation/man/features/kw-deploy.rst000066400000000000000000000137751513255534100234070ustar00rootroot00000000000000========================= kw-deploy - Deploy kernel ========================= .. _deploy-doc: SYNOPSIS ======== *kw* (*d* | *deploy*) [\--remote : | \--local] [\--setup] [-r | \--reboot] [\--no-reboot] [-m | \--modules] [-s | \--ls-line] [-l | \--list] [-a | \--list-all] [(-u | \--uninstall) [[,...]]] [-f \--force] [\--alert=(s | v | (sv | vs) | n)] [-p | \--create-package] [(-F | \--from-package) ] DESCRIPTION =========== If you are in a kernel directory, this command will try to install the current kernel version in your target machine (remote, host, and VM). If you want to install a kernel version in a remote machine, the following steps will be executed: 1. Prepare a local directory with all the required files; 2. Send all the files to the target machine; and 3. Execute the operations that will update the target machine. 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 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:: 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 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:: kw config deploy.reboot_after_deploy yes This can be used with conjunction the :ref:`build` command by invoking ``kw bd``. OPTIONS ======= \--remote :: Deploy the Kernel image and modules to a machine in the network. \--local: Deploy the Kernel image and modules in the host machine, you will need root access. ``kw deploy --local`` should not be executed with sudo or root. -r, \--reboot: Reboot machine after deploy. \--no-reboot: Do not reboot machine after deploy. \--setup: This command runs a basic setup in the target machine, including installing packages and preparing the distro for the deploy. -m, \--modules: Only install/update modules. -l, \--list: List available kernels in a single column the target. -a, \--list-all: List all available kernels, including the ones not installed by kw. -s, \--ls-line: List available kernels separated by comma. -u ( | regex:)[,...], \--uninstall [( | regex:)[,...]]: Remove a single kernel or multiple kernels; for removing multiple kernels it is necessary to separate them with comma. A regex pattern can also be passed as input, prefixed with 'regex:'. If no kernel name is provided, remove the first kernel managed by kw it encounters. -f, \--force: Remove kernels even if they were not installed by kw (only valid with \--uninstall or -u). Trying to remove a kernel not directly managed by kw can lead to system failures, and it is not recommended; only use it if you are sure about what you are doing. -p, \--create-package: It is possible to create a kw package that can be shared with other users and deployed with kw. This option instructs kw to just generate the package without deploying it; notice that the package will be available in the current folder. -F, \--from-package: You can use this option to deploy a custom kernel from kw package. \--alert=(s | v | (sv | vs) | n): Defines the alert behaviour upon the command completion. | **s** enables sound notification. | **v** enables visual notification. | **sv** or **vs** enables both. | **n** (or any other option) disables notifications (this is the default). .. note:: **Only run commands related to VM after you turn it off**. Under the hood, it executes the mount operation, followed by ``make modules_install`` with a specific target, and finally umounts the QEMU image. EXAMPLES ======== 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:: cd kw d --local --modules For building and installing a new module version based on the current kernel version, you can use:: cd kw bd Now, let's say that you set up your configuration file to deploy your new kernel to a machine reachable via ssh. You can run the following command in order to prepare your target machine to receive your new kernel via `kw d`:: kw deploy --setup Alternatively, you can just run `kw d` directly; the standard behavior will automatically run the setup operation in your first deploy. Suppose that you want to share a specific kernel with someone else for validation; you can generate a kw package with:: kw deploy --create-package The above command will create a \*.kw.tar package file that can be shared with 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]' 4) Removes the first kernel managed by kw: kw deploy --uninstall kworkflow-0.10/documentation/man/features/kw-device.rst000066400000000000000000000015641513255534100233430ustar00rootroot00000000000000========================================= kw-device - Retrieve hardware information ========================================= .. _device-doc: SYNOPSIS ======== *kw device* [\--local | \--remote [:] [\--verbose] DESCRIPTION =========== In order to easily retrieve basic information about the hardware of a target machine, kw provides the **device** option, which outputs details such as: | - CPU architecture | - RAM | - Operating system | - Storage device | - GPU OPTIONS ======= \--local: Show hardware information from host machine. \--remote [:]: Show hardware information from remote machine. \--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. kworkflow-0.10/documentation/man/features/kw-diff.rst000066400000000000000000000014041513255534100230050ustar00rootroot00000000000000=================== kw-diff - Diff tool =================== .. _diff-doc: SYNOPSIS ======== *kw* (*df* | *diff*) [\--no-interactive] [\--verbose] DESCRIPTION =========== This is a wrapper to some useful usage of the diff command. By default, it shows diff files side-by-side in an interactive way. If instead of files, two directories are passed to the command, it shows which files are on but not on . OPTIONS ======= \--no-interactive: This option displays all diff in two columns at once. \--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. kworkflow-0.10/documentation/man/features/kw-drm.rst000066400000000000000000000104351513255534100226630ustar00rootroot00000000000000============================ kw-drm - DRM subsystem tools ============================ .. _drm-doc: SYNOPSIS ======== | *kw* *drm* [\--local | \--remote [:]] | [\--load-module=[:,...][;:...] | | \--unload-module=[;;...] | | \--gui-on | \--gui-off | \--conn-available | \--modes | \--verbose] DESCRIPTION =========== Linux kernel has multiple subsystems that expose operations via sysfs or provide mechanisms for userspace to interact with the driver. For this reason, kw offers some options that target some specific subsystems for providing facilities for users to interact with a particular subsystem. Currently, we only support drm. This feature is responsible to deal with DRM features. 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** 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**. \--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 parameters for the target module, they have to use ':' and separate each parameter with ','. This option can be combined with ``--gui-on``, **kw** will make sure that the target module will be load first and after that trigger the GUI. \--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. \--gui-on: This option provides a mechanism for turn-on the GUI, 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* on the **kworkflow.config** file. \--gui-off: Turn off the target GUI in the specified target, by default, it uses the 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. The ones marked with '*' are enabled. \--modes: Show all available modes per card. \--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. EXAMPLES ======== 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:: kw drm --load-module='amdgpu' --gui-on # Load a driver and trigger the user GUI kw drm --unload-module='amdgpu' # Turn off user GUI and unload the driver .. note:: You have to wait for the sshd to become ready. kworkflow-0.10/documentation/man/features/kw-env.rst000066400000000000000000000053031513255534100226670ustar00rootroot00000000000000=============================== kw-env - kw environment manager =============================== .. _env-doc: SYNOPSIS ======== | *kw* (*env*) [(-c | \--create) ] | *kw* (*env*) [(-u | \--use) ] | *kw* (*env*) [(-d | \--destroy )] | *kw* (*env*) [(-l | \--list)] | *kw* (*env*) [(-e | \--exit-env)] | *kw* (*env*) [\--verbose] DESCRIPTION =========== When working with the Linux kernel, we might want to run different tests to fix some specific issues. One typical example is when a developer works with 64-bit architecture but has to check if the 32-bit compilation works fine; this effort requires changes in the config file and other parts. Another case is when a developer uses the same kernel for a test machine with configuration X, but they also need to check another device with configuration Y. kw env makes the developer's life easier by isolating multiple contexts in their environment. When you create a new env, kw will isolate: 1. All kw configs per env. This means that you can have one dedicated configuration per env; 2. Associate the kernel config file with the new env. In other words, in the same kernel, you can have different kernel configs file per env; 3. Isolate compiled file per env. .. note:: kw does not support the concept of global env. You must have one env per kernel repository. OPTIONS ======= -c, \--create : The create parameter expects a string to be used as an env name. When kw create a new env it instantiates the current kw configurations to the new env. -u, \--use : Change from one env to another previously created. -d, \--destroy : The destroy parameter expects a string with the name of the env you want to destroy. -l, \--list: It shows all envs created via `\--create` option. -e, \--exit-env: Allow users to "exit" the env feature. If the user is using a specific env and doesn't want to use it anymore, the `--exit-env` option will remove all symbolic links and copy the current env's configuration files to the .kw. \--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. EXAMPLES ======== If you want to create a new env, you can use:: cd kw env --create MY_NEW_ENV kw env --create 32-BIT-COMPILATION If you want to create a new env, you can use:: kw env --use 32-BIT-COMPILATION If you want to destroy an environment:: kw env --destroy MY_NEW_ENV kw env --destroy 32-BIT-COMPILATION If you want to list the available envs:: kw env --list If you want to exit the env feature:: kw env --exit-env kworkflow-0.10/documentation/man/features/kw-explore.rst000066400000000000000000000046171513255534100235640ustar00rootroot00000000000000=========================== kw-explore - Explore folder =========================== .. _explore-doc: SYNOPSIS ======== *kw* (*e* | *explore*) [(-l | \--log) | (-g | \--grep) | (-a | \--all) | \--verbose] [(-c | \--only-source) | (-H | \--only-header)] [(-C[] | \--show-context[=])] [-p] [ | ] DESCRIPTION =========== The **explore** command is, by default, a wrapper to git grep, searching for string matches in files under git control or in the git log messages. Additional parameters extended its behavior to cover all files in a directory (whether or not controlled by git) and also to replace the search tool with the GNU grep utility. Default usage: you can use ``kw e `` to find ** in the source directory; If your string has spaces in it you have to quote your search (e.g., ``kw e " "``). OPTIONS ======= -l, \--log: Search the git log history by using **\--log** after the **e**; for instance, ``kw e --log ``. Additionally, you can use **-p** to see the diff in the search. -g, \--grep: Search for string matches in directory contents using GNU grep tool. For instance, ``kw e --grep ``. It also covers files inside .git directory. -a, \--all: Search for string matches in directory contents using Git grep tool. For instance, ``kw e --all ``. With this, the search ignores files inside .git, except if it is called inside .git directory. In other words, if you use this option you will notice that ``git grep`` is used first, and then GNU grep. -c | \--only-source: With this option, it is possible to show only the results from the source. -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 kworkflow-0.10/documentation/man/features/kw-init.rst000066400000000000000000000051771513255534100230530ustar00rootroot00000000000000====================================== kw-init - Create kw basic config files ====================================== .. _init-doc: SYNOPSIS ======== | *kw* *init* [\--verbose] [\--template[=name]] | *kw* *init* [\--verbose] [\--arch ][\--remote @:][\--target ] DESCRIPTION =========== 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 freshly created config files. OPTIONS ======= \--template[=name]: kw supports some pre-defined configurations for specific targets, and users can select them using the template parameter. If the user does not provide any input, kw will show all the available templates, and the user just needs to pick one. If the user provides the template name, kw will use it for creating the local config file. \--arch : 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. \--remote @:: Set the variables `ssh_user`, `ssh_ip`, and `ssh_port` to **, **, and **, respectively. \--target : Set the variable `default_deploy_target` from **deploy.config** to **, which can be local or remote. \--verbose: Verbose mode allows the user to see the commands executed under the hood. EXAMPLES ======== For these examples, we suppose that the kernel directory is your current directory. For initializing a **build.config** with `arch` set to arm, use:: kw init --arch arm 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 **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 Kw provides some default templates that can be useful for the first setup. Users can see and interactively select the target option by using:: kw init --template Alternatively, if the user knows which template they want to use:: kw init --template=rpi4-and-5-raspbian-64-cross-x86-arm Keep in mind that you are still able to combine other parameters with the template feature, for example:: kw init --template=rpi4-and-5-raspbian-64-cross-x86-arm --remote mary@localhost:1234 --target remote kworkflow-0.10/documentation/man/features/kw-kernel-config-manager.rst000066400000000000000000000071671513255534100262440ustar00rootroot00000000000000===================================================== kw-kernel-config-manager - Kernel config file manager ===================================================== .. _kernel-config-manager-doc: SYNOPSIS ======== | *kw* (*k* | *kernel-config-manager*) [(-s | \--save) [(-d | \--description) ] [-f | \--force]] | *kw* (*k* | *kernel-config-manager*) [-l | \--list] | *kw* (*k* | *kernel-config-manager*) [\--fetch [(-o | \--output) ] [-f | \--force] [\--optimize] [\--remote [:]]]: | *kw* (*k* | *kernel-config-manager*) [\--get [-f | \--force]] | *kw* (*k* | *kernel-config-manager*) [(-r | \--remove) [-f | \--force]] | *kw* (*k* | *kernel-config-manager*) [\--verbose]] DESCRIPTION =========== The **kernel-config-manager** command manages different versions of the project's **.config** file. It provides the save, load, remove, and list operations of such files. By default, if the user does not provide any parameter, the kernel-config-manager will list all configs under **kw**'s management. .. note:: This feature has interoperability with the kw env feature. OPTIONS ======= \--save [-d ] [-f | \--force]: The save option creates a snapshot of the **.config** file in the current folder in **kw**'s management system under the specified **. Additionally, users can add a description by using the ``-d`` flag. Finally, if the user tries to add another config with a name that's already being managed, **kw** will issue a warning; ``-f`` will suppress such a warning. -l, \--list: Lists all the **.config** file versions available. This is also the default behavior when no option is specified. \--get [-f | \--force]: Get a copy of the config file with the provided ** in the current directory. As this operation overwrites the current **.config** file a warning is shown; ``-f`` will suppress such a warning and carry on any destructive operations. -r [-f | \--force], \--remove [-f | \--force]: Remove config labeled with ** from **kw**'s management system. As this operation removes a **.config** file from kw management a warning is shown; ``-f`` will suppress such a warning and carry on any destructive operations. \--fetch [(-o | \--output) ] [-f | \--force] [\--optimize] [\--remote [:]]: Fetches a **.config** file from a target machine to your current directory. If another config is found in this directory, then **kw** will ask you whether you want to replace it or not; ``-f`` will suppress such a warning and carry on any destructive operations. ``--output`` allows you to specify the config file name, and ``--optimize`` will run `make localmodconfig` in order to generate a config that's optimized for the target machine. \--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. EXAMPLES ======== 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:: cd kw k --save my_current_config You can see the config's file maintained by **kw** with:: kw k --list If you want to fetch a config from a remote machine (available at ``localhost:2222``) as root, you can run:: kw kernel-config-manager --fetch --remote root@localhost:2222 kworkflow-0.10/documentation/man/features/kw-maintainers.rst000066400000000000000000000032151513255534100244110ustar00rootroot00000000000000=========================================== kw-maintainers - Display module maintainers =========================================== .. _maintainers-doc: SYNOPSIS ======== *kw* (*m* | *maintainers*) [-a | \--authors] [-u | \--update-patch] [\--verbose] [ | ] DESCRIPTION =========== Based on the Linux Kernel get_maintainers script, this command shows the maintainers of a given Kernel module (a given file or directory). The ``--authors`` option will also print the authors of the top-level target files (non-recursively). Files with more than one author will have their names separated by ",". This output should not be used by scripts because some authors include "," in their names (e.g. "Company X, Inc."). The ``--update-patch`` will update the patch **'s header with a **To:** field with the maintainers (excluding the authors) associated with that patch. OPTIONS ======= -a, \--authors: Prints the authors of the top-level target files (non-recursively). Files with more than one author will have their names separated by ",". -u, \--update-patch: It will include a **To:** field in the header of the patch file with the contact of the maintainers (excluding the authors) associated with that patch. \--verbose: Display commands executed under the hood. EXAMPLES ======== 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:: cd kw m drivers/iio/dummy/iio_simple_dummy.c kworkflow-0.10/documentation/man/features/kw-patch-hub.rst000066400000000000000000000022161513255534100237520ustar00rootroot00000000000000======================================================================== kw-patch-hub - Terminal UI to interact with patches from lore.kernel.org ======================================================================== .. _patch-hub-doc: SYNOPSIS ======== | *kw patch-hub* DESCRIPTION =========== The `kw patch-hub` feature provides a TUI (*Terminal User Interface*) that streamlines the interaction of Linux developers with patches archived on lore.kernel.org. The feature can be used to just consult patchsets from a target list, but, as it integrates with other kw features, it simplifies the process of reviewing patchset, like: - Applying a patchset to a git tree - Building the patchset version of the Linux kernel - Deploying the patchset version of the Linux kernel - Replying with `Reviewed-by/Tested-by` tags `kw patch-hub` is an integrated interface to automate and simplify these actions. .. note:: `patch-hub` is a `standalone sub-project `_ from the kw organization and it is under heavy development. We welcome contributions! EXAMPLES ======== To launch `kw patch-hub` simply run:: kw patch-hub kworkflow-0.10/documentation/man/features/kw-pomodoro.rst000066400000000000000000000064741513255534100237470ustar00rootroot00000000000000=============================================== kw-pomodoro - Create and manage Pomodoro timers =============================================== .. _pomodoro-doc: SYNOPSIS ======== | *kw* (*p* | *pomodoro*) (-t | \--set-timer)