tools/tryselect/docs/tasks.rst

   1 Task Generation
   2 ===============
   3
   4 Many selectors (including ``chooser``, ``coverage`` and ``fuzzy``) source their available tasks
   5 directly from the :ref:`taskgraph <TaskCluster Task-Graph Generation>` module by building the taskgraph
   6 locally. This means that the list of available tasks will never be stale. While this is very
   7 powerful, it comes with a large enough performance cost to get annoying (around twenty seconds).
   8
   9 The result of the taskgraph generation will be cached, so this penalty will only be incurred
  10 whenever a file in the ``/taskcluster`` directory is modified. Unfortunately this directory changes
  11 pretty frequently, so developers can expect to rebuild the cache each time they pull in
  12 ``mozilla-central``. Developers who regularly work on ``/taskcluster`` can expect to rebuild even
  13 more frequently.
  14
  15
  16 Configuring Watchman
  17 --------------------
  18
  19 It's possible to bypass this penalty completely by using the file watching service `watchman`_. If
  20 you use the ``fsmonitor`` mercurial extension, you already have ``watchman`` installed.
  21
  22 .. note::
  23
  24     If you aren't using `fsmonitor`_ but end up installng watchman anyway, you
  25     might as well enable it for a faster Mercurial experience.
  26
  27 Otherwise, `install watchman`_. If using Linux you'll likely run into the `inotify limits`_ outlined
  28 on that page due to the size of ``mozilla-central``. You can `read this page`_ for more information
  29 on how to bump the limits permanently.
  30
  31 Next run the following commands:
  32
  33 .. code-block:: shell
  34
  35     $ cd path/to/mozilla-central
  36     $ watchman watch .
  37     $ watchman -j < tools/tryselect/watchman.json
  38
  39 You should see output like:
  40
  41 .. code-block:: json
  42
  43     {
  44         "triggerid": "rebuild-taskgraph-cache",
  45         "disposition": "created",
  46         "version": "20200920.192359.0"
  47     }
  48
  49 That's it. Now anytime a file under ``/taskcluster`` is modified (either by your editor, or by
  50 updating version control), the taskgraph cache will be rebuilt in the background, allowing you to
  51 skip the wait the next time you run ``mach try``.
  52
  53 .. note::
  54
  55     Watchman triggers are persistent and don't need to be added more than once.
  56     See `Managing Triggers`_ for how to remove a trigger.
  57
  58 You can test that everything is working by running these commands:
  59
  60 .. code-block:: shell
  61
  62     $ statedir=`mach python -c "from mach.util import get_state_dir; print(get_state_dir(specific_to_topsrcdir=True))"`
  63     $ rm -rf $statedir/cache/taskgraph
  64     $ touch taskcluster/mach_commands.py
  65     # wait a minute for generation to trigger and finish
  66     $ ls $statedir/cache/taskgraph
  67
  68 If the ``target_task_set`` file exists, you are good to go. If not you can look at the ``watchman``
  69 log to see if there were any errors. This typically lives somewhere like
  70 ``/usr/local/var/run/watchman/$USER-state/log``. In this case please file a bug under ``Firefox
  71 Build System :: Try`` and include the relevant portion of the log.
  72
  73
  74 Running Watchman on Startup
  75 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  76
  77 Watchman is both a client and a service all in one. When running a ``watchman`` command, the client
  78 binary will start the service in the background if it isn't running. This means on reboot the
  79 service won't be running and you'll need to start the service each time by invoking the client
  80 binary (e.g by running ``watchman version``).
  81
  82 If you'd like this to happen automatically, you can use your favourite platform specific way of
  83 running commands at startup (``crontab``, ``rc.local``, etc.). Watchman stores separate state for
  84 each user, so be sure you run the command as the user that set up the triggers.
  85
  86 Setting up a systemd Service
  87 ++++++++++++++++++++++++++++
  88
  89 If ``systemd`` is an option you can create a service:
  90
  91 .. code-block:: ini
  92
  93     [Unit]
  94     Description=Watchman for %i
  95     After=network.target
  96
  97     [Service]
  98     Type=simple
  99     User=%i
 100     ExecStart=/usr/local/bin/watchman --log-level 1 watch-list -f
 101     ExecStop=/usr/local/bin/watchman shutdown-server
 102
 103     [Install]
 104     WantedBy=multi-user.target
 105
 106 Save this to a file called ``/etc/systemd/system/watchman@.service``. Then run:
 107
 108 .. code-block:: shell
 109
 110     $ sudo systemctl enable watchman@$USER.service
 111     $ sudo systemctl start watchman@$USER.service
 112
 113 The next time you reboot, the watchman service should start automatically.
 114
 115
 116 Managing Triggers
 117 ~~~~~~~~~~~~~~~~~
 118
 119 When adding a trigger watchman writes it to disk. Typically it'll be a path similar to
 120 ``/usr/local/var/run/watchman/$USER-state/state``. While editing that file by hand would work, the
 121 watchman binary provides an interface for managing your triggers.
 122
 123 To see all directories you are currently watching:
 124
 125 .. code-block:: shell
 126
 127     $ watchman watch-list
 128
 129 To view triggers that are active in a specified watch:
 130
 131 .. code-block:: shell
 132
 133     $ watchman trigger-list <path>
 134
 135 To delete a trigger from a specified watch:
 136
 137 .. code-block:: shell
 138
 139     $ watchman trigger-del <path> <name>
 140
 141 In the above two examples, replace ``<path>`` with the path of the watch, presumably
 142 ``mozilla-central``. Using ``.`` works as well if that is already your working directory. For more
 143 information on managing triggers and a reference of other commands, see the `official docs`_.
 144
 145
 146 .. _watchman: https://facebook.github.io/watchman/
 147 .. _fsmonitor: https://www.mercurial-scm.org/wiki/FsMonitorExtension
 148 .. _install watchman: https://facebook.github.io/watchman/docs/install.html
 149 .. _inotify limits: https://facebook.github.io/watchman/docs/install.html#linux-inotify-limits
 150 .. _read this page: https://github.com/guard/listen/wiki/Increasing-the-amount-of-inotify-watchers
 151 .. _this hint: https://github.com/facebook/watchman/commit/2985377eaf8c8538b28fae9add061b67991a87c2
 152 .. _official docs: https://facebook.github.io/watchman/docs/cmd/trigger.html