Provided by: kworkflow_20191112-1.2_amd64 bug

NAME

       kw - Inglorious kernel developer workflow scripts

SYNOPSIS

       kw COMMAND [OPTION ...]

DESCRIPTION

       kw  is  a  set  of  scripts  that  have a single mission: reduce the overhead related with
       infrastructure project setup in projects that have a similar workflow to the Linux Kernel.
       It  can  (and  should) be customized by editing the kworkflow.config file, as discussed in
       section "ABOUT kworflow.config".

COMMANDS

       kw offers several subcommands catering to  different  audiences  and  targeting  different
       functionality groups. Most subcommands have sane defaults.

   COMMANDS FOR USING QEMU
       Projects  that  use a QEMU VM in the development cycle to host the development environment
       usually require that developers use some specific commands to  manage  this  VM.  In  this
       section,  you  can find all commands available in kw to manage many daily tasks related to
       QEMU VM operation.  Notice that some rules are specific for the Linux Kernel project.

   mo, mount
       Mount the QEMU image in  a  specific  directory,  based  on  the  data  available  in  the
       kworkflow.config.  Notice that the configuration file has the information about the source
       image and destiny mount point.

       NOTE:
          Only run this command after you turn off your VM.

   um, umount
       Umount the previously mounted QEMU image.

   u, up
       Start the QEMU VM based on parameters in the kworkflow.config file.

   s, ssh [--script|-s="PATH"]|[--command|-c="COMMAND"]
       Ssh into the QEMU VM. The --script parameter expects a  bash  script  as  a  parameter  to
       evaluate it in the VM. The --command parameter expects a command to be executed inside the
       QEMU VM.

   i, install
       Installs or updates the Linux kernel modules on the QEMU VM. Under the hood,  it  executes
       the  mount operation, followed by make modules_install with a specific target, and finally
       umounts the QEMU image.

       NOTE:
          Only run this command after you turn off your VM.

   p, prepare
       (EXPERIMENTAL) Starting from a generic image, prepare  sets  up  the  necessary  packages,
       files,  etc.  inside  the QEMU image so that it is ready for development work. For this to
       work, you have to:

       1. Add your public key in the VM in the authorized_keys file.

       2. Remove the requirement for password in the VM to become root.

       This command (currently) uses Ansible playbooks.

   COMMANDS FOR WORKING WITH CODE
       Projects that have a similar workflow to the Linux Kernel usually have a set of tools that
       simplify  part  of the tasks related with the code. This section describes some of the key
       features supported by kw to help with code.

   b, build
       This command calls make on a local Makefile  to  build  the  project.  It  tries  to  take
       advantage of your hardware by using the -j option with the appropriate parameter.

   c, codestyle [DIRECTORY|FILE]
       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 or an entire directory.

   e, explore [log] [EXPRESSION] [-p] [DIRECTORY|FILE]
       The explore command is based on git grep. It can search for string matches in  either  the
       git  repository  contents  or  in  the  git  log  messages.  For example, you can use kw e
       functionName to find functionName in the source directory.  You can also  search  the  git
       log  history by using log after the e; for instance, kw e log STRING_MATCH.  Additionally,
       you can use -p to see the diff in the search.

   m, maintainers [-a|--authors] [DIRECTORY|FILE]
       Based on the Linux Kernel get_maintainers script, this command shows the maintainers of  a
       given  Kernel  module  (a  given  file or directory).  The [-a|--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.").

   OTHER COMMANDS
       This section  describes  a  tool  available  in  kw  to  help  developers  keep  track  of
       configuration  files  and  other  features  provided by kw that do not fit in the previous
       sections.

   g, configm [--save NAME [-d DESCRIPTION][-f]]|[--ls]|[--get NAME [-f]]|[--rm NAME [-f]]
       The 'configm' command manages different versions of  the  project's  '.config'  file.   It
       provides the save, load, remove, and list operations of such files.

       1.   --save NAME [-d DESCRIPTION] [-f]: The save option searches the current directory for
       a '.config' file to be kept under the management of kw. The save option expects a name  to
       identify  this  version of the file. Additionally, users can add a description by using -d
       flag. Finally, if the user tries to add the same name twice, kw will issue a warning;  the
       '-f' will suppress this message.

       2. --ls lists all the .config file versions available.

       3.  --get  NAME  [-f]:  Get  a  config  file based on the NAME and paste it in the current
       directory. It pop-up a warning message because this operation override the current .config
       file. The user can suppress this warning by using -f flag.

       4. --rm NAME [-f]: Remove config labeled with NAME. It pop-up a warning message because it
       will remove the config file from kw management. The user  can  suppress  this  warning  by
       using -f.

   v, vars
       Shows  configurations  being  used  by kw in the current working directory. To do that, it
       examines both global and local kworkflow.config files.

   bi
       Build and install a new module version. It is a  combination  of  the  build  and  install
       commands.

   alert=[vs|sv,v,s,n]
       Some  commands  take  considerable  time to execute. kw gives you an option to be notified
       when they finish. The commands prepare, build, install, mount, umount, new  and  bi  offer
       this feature.

       1. v enables visual notification.

       2. s enables sound notification.

       3. vs or sv enables both.

       4. n (or any other option) disables notifications (this is the default).

   h, help
       Show basic help.

ABOUT KWORFLOW.CONFIG

       kw  reads  its configuration from two files: the global PATH/etc/kworkflow.config file and
       the local kworkflow.config file present at  the  current  working  directory.  The  global
       kworkflow.config  is a part of the kw code and provides the overall behavior for kw. Local
       kworkflow.config settings override global ones; you  may  have  one  kworkflow.config  per
       project.  In  this  section,  we  describe  the  possible  fields  you  can specify in the
       configuration files.

   ssh_ip=IP
       Sets the IP address to be used by ssh. By default kw uses localhost.

   ssh_port=PORT
       Sets the ssh port. By default kw uses 2222.

   arch=ARCHITECTURE
       Allows you to specify the default architecture used by kw. By default, kw uses x86_64.

   virtualizer=VIRTUALIZER
       Defines the virtualization tool that should be used by kw. Currently, we only support QEMU
       and, as a result, the default is qemu-system-x86_64

   mount_point=PATH
       Defines  the  kw  mount  point,  which  will be used by libguestfs during the mount/umount
       operation of a VM. By default, kw uses /home/$USER/p/mount.

   qemu_hw_options=OPTIONS
       Sets QEMU options. By default, kw uses -enable-kvm -daemonize -smp 2 -m 1024

   qemu_net_options=OPTIONS
       Defines   the   network   configuration.   By   default,   kw   uses   -net    nic    -net
       user,hostfwd=tcp::2222-:22,smb=/home/USER

   qemu_path_image=PATH
       Specify the VM image path. By default, kw uses /home/USERKW/p/virty.qcow2

   alert=[vs|s|v|n]
       Default alert options, you have:

       1. v: enables visual notification.

       2. s enables sound notification.

       3. vs or sv enables both.

       4. n (or any other option) disables notifications.

   sound_alert_command=COMMAND
       Command   to   run   for   sound   completion   alert.   By   default,   kw   uses  paplay
       INSTALLPATH/sounds/complete.wav &

   visual_alert_command=COMMAND
       Command to run for visual completion alert. By default, kw uses notify-send -i checkbox -t
       10000  "kw"  "Command:  \"$COMMAND\" completed!" (Note: You may use COMMAND, which will be
       replaced by the kw command whose conclusion the user wished to be alerted.)

EXAMPLE

       For these examples, we suppose  the  fields  in  your  kworkflow.config  file  is  already
       configured.

       First,  if  you  are  working in a specific kernel module, and if you want to install your
       recent changes in your VM you can use:

          cd /KERNEL/PATH
          kw i

       NOTE:
          Turn off your VM before use the intall command.

       For building and installing a new module version based on the current kernel version,  you
       can use:

          cd /KERNEL/PATH
          kw bi

       For checking the code style:

          cd /KERNEL/PATH
          kw c drivers/iio/dummy/
          kw c drivers/iio/dummy/iio_simple_dummy.c

       If you want to check the maintainers:

          cd /KERNEL/PATH
          kw m drivers/iio/dummy/iio_simple_dummy.c

       In case you want that kw saves your current .config file, you can use:

          cd /KERNEL/PATH
          kw g --save my_current_config

       You can see the config's file maintained by kw with:

          kw g --ls

       You can turn on your VM with:

          kw u

       After you start your VM you can ssh into it with:

          kw s -c="dmesg -wH"
          kw s

       NOTE:
          You have to wait for the sshd become ready.

AUTHOR

       Rodrigo        Siqueira       <rodrigosiqueiramelo@gmail.com>,       Matheus       Tavares
       <matheus.bernardino@usp.br>

COPYRIGHT

       GPLv2+

                                            2018-05-18                                      KW(1)