faq.rst (5496B)
1 .. _mach_faq: 2 3 ========================== 4 Frequently Asked Questions 5 ========================== 6 7 How do I report bugs? 8 --------------------- 9 10 Bugs against the ``mach`` core can be filed in Bugzilla in the `Firefox 11 Build System::Mach 12 Core <https://bugzilla.mozilla.org/enter_bug.cgi?product=Firefox%20Build%20System&component=Mach%20Core>`__ component. 13 14 .. note:: 15 16 Most ``mach`` bugs are bugs in individual commands, not bugs in the core 17 ``mach`` code. Bugs for individual commands should be filed against the 18 component that command is related to. For example, bugs in the 19 *build* command should be filed against *Firefox Build System :: 20 General*. Bugs against testing commands should be filed somewhere in 21 the *Testing* product. 22 23 How do I debug a command failing with a Python exception? 24 --------------------------------------------------------- 25 26 You can run a command and break into ``pdb``, the Python debugger, 27 when the command is invoked with: 28 29 .. code-block:: shell 30 31 ./mach --debug-command FAILING-COMMAND ARGS ... 32 33 How do I debug ``mach`` itself? 34 ------------------------------- 35 36 If you are editing the mach code, or other Python modules you can 37 open the terminal and start debugging with pdb with the following: 38 39 .. code-block:: shell 40 41 python3 -m pdb ./mach <command> 42 43 How do I debug ``pytest`` tests? 44 -------------------------------- 45 46 First, before debugging, run ``./mach python-test`` once to ensure that 47 the testing virtualenv is up-to-date: 48 49 .. code-block:: shell 50 51 ./mach python-test path/to/test.py 52 53 Then, using the testing virtualenv, debug the test file: 54 55 .. code-block:: shell 56 57 <objdir>/_virtualenvs/python-test/bin/python -m pdb path/to/test.py 58 59 How do I profile a slow command? 60 -------------------------------- 61 62 To diagnose bottlenecks, you can collect a performance profile: 63 64 .. code-block:: shell 65 66 ./mach --profile-command SLOW-COMMAND ARGS ... 67 68 Then, you can visualize ``mach_profile_SLOW-COMMAND.cProfile`` using 69 `snakeviz <https://jiffyclub.github.io/snakeviz/>`__: 70 71 .. code-block:: shell 72 73 # If you don't have snakeviz installed yet: 74 python3 -m pip install snakeviz 75 python3 -m snakeviz mach_profile_SLOW-COMMAND.cProfile 76 77 How do I profile ``mach`` itself? 78 --------------------------------- 79 80 Since ``--profile-command`` only profiles commands, you'll need to invoke ``cProfile`` 81 directly to profile ``mach`` itself: 82 83 .. code-block:: shell 84 85 python3 -m cProfile -o mach.cProfile ./mach ... 86 python3 -m snakeviz mach.cProfile 87 88 Is ``mach`` a build system? 89 --------------------------- 90 91 No. ``mach`` is just a generic command dispatching tool that happens to have 92 a few commands that interact with the real build system. Historically, 93 ``mach`` *was* born to become a better interface to the build system. 94 However, its potential beyond just build system interaction was quickly 95 realized and ``mach`` grew to fit those needs. 96 97 How do I add features to ``mach``? 98 ---------------------------------- 99 If you would like to add a new feature to ``mach`` that cannot be implemented as 100 a ``mach`` command, the first step is to file a bug in the 101 ``Firefox Build System :: Mach Core`` component. 102 103 Should I implement X as a ``mach`` command? 104 ------------------------------------------- 105 106 There are no hard or fast rules. Generally speaking, if you have some 107 piece of functionality or action that is useful to multiple people 108 (especially if it results in productivity wins), then you should 109 consider implementing a ``mach`` command for it. 110 111 Some other cases where you should consider implementing something as a 112 ``mach`` command: 113 114 - When your tool is a random script in the tree. Random scripts are 115 hard to find and may not conform to coding conventions or best 116 practices. ``Mach`` provides a framework in which your tool can live that 117 will put it in a better position to succeed than if it were on its 118 own. 119 - When the alternative is a ``make`` target. The build team generally does 120 not like one-off ``make`` targets that aren't part of building (read: 121 compiling) the tree. This includes things related to testing and 122 packaging. These weigh down ``Makefiles`` and add to the burden of 123 maintaining the build system. Instead, you are encouraged to 124 implement ancillary functionality in Python. If you do implement something 125 in Python, hooking it up to ``mach`` is often trivial. 126 127 How do I use 3rd-party Python packages in my ``mach`` command? 128 -------------------------------------------------------------- 129 130 See :ref:`Using third-party Python packages`. 131 132 How does ``mach`` fit into the modules system? 133 ---------------------------------------------- 134 135 Mozilla operates with a `modules governance 136 system <https://www.mozilla.org/about/governance/policies/module-ownership/>`__ where 137 there are different components with different owners. There is not 138 currently a ``mach`` module. There may or may never be one; currently ``mach`` 139 is owned by the build team. 140 141 Even if a ``mach`` module were established, ``mach`` command modules would 142 likely never belong to it. Instead, ``mach`` command modules are owned by the 143 team/module that owns the system they interact with. In other words, ``mach`` 144 is not a power play to consolidate authority for tooling. Instead, it aims to 145 expose that tooling through a common, shared interface. 146 147 148 Who do I contact for help or to report issues? 149 ---------------------------------------------- 150 151 You can ask questions in 152 `#build <https://chat.mozilla.org/#/room/#build:mozilla.org>`__.