|
| 1 | +=========== |
| 2 | +QEMU README |
| 3 | +=========== |
| 4 | + |
| 5 | +QEMU is a generic and open source machine & userspace emulator and |
| 6 | +virtualizer. |
| 7 | + |
| 8 | +QEMU is capable of emulating a complete machine in software without any |
| 9 | +need for hardware virtualization support. By using dynamic translation, |
| 10 | +it achieves very good performance. QEMU can also integrate with the Xen |
| 11 | +and KVM hypervisors to provide emulated hardware while allowing the |
| 12 | +hypervisor to manage the CPU. With hypervisor support, QEMU can achieve |
| 13 | +near native performance for CPUs. When QEMU emulates CPUs directly it is |
| 14 | +capable of running operating systems made for one machine (e.g. an ARMv7 |
| 15 | +board) on a different machine (e.g. an x86_64 PC board). |
| 16 | + |
| 17 | +QEMU is also capable of providing userspace API virtualization for Linux |
| 18 | +and BSD kernel interfaces. This allows binaries compiled against one |
| 19 | +architecture ABI (e.g. the Linux PPC64 ABI) to be run on a host using a |
| 20 | +different architecture ABI (e.g. the Linux x86_64 ABI). This does not |
| 21 | +involve any hardware emulation, simply CPU and syscall emulation. |
| 22 | + |
| 23 | +QEMU aims to fit into a variety of use cases. It can be invoked directly |
| 24 | +by users wishing to have full control over its behaviour and settings. |
| 25 | +It also aims to facilitate integration into higher level management |
| 26 | +layers, by providing a stable command line interface and monitor API. |
| 27 | +It is commonly invoked indirectly via the libvirt library when using |
| 28 | +open source applications such as oVirt, OpenStack and virt-manager. |
| 29 | + |
| 30 | +QEMU as a whole is released under the GNU General Public License, |
| 31 | +version 2. For full licensing details, consult the LICENSE file. |
| 32 | + |
| 33 | + |
| 34 | +Documentation |
| 35 | +============= |
| 36 | + |
| 37 | +Documentation can be found hosted online at |
| 38 | +`<https://www.qemu.org/documentation/>`_. The documentation for the |
| 39 | +current development version that is available at |
| 40 | +`<https://www.qemu.org/docs/master/>`_ is generated from the ``docs/`` |
| 41 | +folder in the source tree, and is built by `Sphinx |
| 42 | +<https://www.sphinx-doc.org/en/master/>`_. |
| 43 | + |
| 44 | + |
| 45 | +Building |
| 46 | +======== |
| 47 | + |
| 48 | +QEMU is multi-platform software intended to be buildable on all modern |
| 49 | +Linux platforms, OS-X, Win32 (via the Mingw64 toolchain) and a variety |
| 50 | +of other UNIX targets. The simple steps to build QEMU are: |
| 51 | + |
| 52 | + |
| 53 | +.. code-block:: shell |
| 54 | +
|
| 55 | + mkdir build |
| 56 | + cd build |
| 57 | + ../configure |
| 58 | + make |
| 59 | +
|
| 60 | +Additional information can also be found online via the QEMU website: |
| 61 | + |
| 62 | +* `<https://wiki.qemu.org/Hosts/Linux>`_ |
| 63 | +* `<https://wiki.qemu.org/Hosts/Mac>`_ |
| 64 | +* `<https://wiki.qemu.org/Hosts/W32>`_ |
| 65 | + |
| 66 | + |
| 67 | +Submitting patches |
| 68 | +================== |
| 69 | + |
| 70 | +The QEMU source code is maintained under the GIT version control system. |
| 71 | + |
| 72 | +.. code-block:: shell |
| 73 | +
|
| 74 | + git clone https://gitlab.com/qemu-project/qemu.git |
| 75 | +
|
| 76 | +When submitting patches, one common approach is to use 'git |
| 77 | +format-patch' and/or 'git send-email' to format & send the mail to the |
| 78 | +[email protected] mailing list. All patches submitted must contain |
| 79 | +a 'Signed-off-by' line from the author. Patches should follow the |
| 80 | +guidelines set out in the `style section |
| 81 | +<https://www.qemu.org/docs/master/devel/style.html>`_ of |
| 82 | +the Developers Guide. |
| 83 | + |
| 84 | +Additional information on submitting patches can be found online via |
| 85 | +the QEMU website |
| 86 | + |
| 87 | +* `<https://wiki.qemu.org/Contribute/SubmitAPatch>`_ |
| 88 | +* `<https://wiki.qemu.org/Contribute/TrivialPatches>`_ |
| 89 | + |
| 90 | +The QEMU website is also maintained under source control. |
| 91 | + |
| 92 | +.. code-block:: shell |
| 93 | +
|
| 94 | + git clone https://gitlab.com/qemu-project/qemu-web.git |
| 95 | +
|
| 96 | +* `<https://www.qemu.org/2017/02/04/the-new-qemu-website-is-up/>`_ |
| 97 | + |
| 98 | +A 'git-publish' utility was created to make above process less |
| 99 | +cumbersome, and is highly recommended for making regular contributions, |
| 100 | +or even just for sending consecutive patch series revisions. It also |
| 101 | +requires a working 'git send-email' setup, and by default doesn't |
| 102 | +automate everything, so you may want to go through the above steps |
| 103 | +manually for once. |
| 104 | + |
| 105 | +For installation instructions, please go to |
| 106 | + |
| 107 | +* `<https://github.com/stefanha/git-publish>`_ |
| 108 | + |
| 109 | +The workflow with 'git-publish' is: |
| 110 | + |
| 111 | +.. code-block:: shell |
| 112 | +
|
| 113 | + $ git checkout master -b my-feature |
| 114 | + $ # work on new commits, add your 'Signed-off-by' lines to each |
| 115 | + $ git publish |
| 116 | +
|
| 117 | +Your patch series will be sent and tagged as my-feature-v1 if you need to refer |
| 118 | +back to it in the future. |
| 119 | + |
| 120 | +Sending v2: |
| 121 | + |
| 122 | +.. code-block:: shell |
| 123 | +
|
| 124 | + $ git checkout my-feature # same topic branch |
| 125 | + $ # making changes to the commits (using 'git rebase', for example) |
| 126 | + $ git publish |
| 127 | +
|
| 128 | +Your patch series will be sent with 'v2' tag in the subject and the git tip |
| 129 | +will be tagged as my-feature-v2. |
| 130 | + |
| 131 | +Bug reporting |
| 132 | +============= |
| 133 | + |
| 134 | +The QEMU project uses GitLab issues to track bugs. Bugs |
| 135 | +found when running code built from QEMU git or upstream released sources |
| 136 | +should be reported via: |
| 137 | + |
| 138 | +* `<https://gitlab.com/qemu-project/qemu/-/issues>`_ |
| 139 | + |
| 140 | +If using QEMU via an operating system vendor pre-built binary package, it |
| 141 | +is preferable to report bugs to the vendor's own bug tracker first. If |
| 142 | +the bug is also known to affect latest upstream code, it can also be |
| 143 | +reported via GitLab. |
| 144 | + |
| 145 | +For additional information on bug reporting consult: |
| 146 | + |
| 147 | +* `<https://wiki.qemu.org/Contribute/ReportABug>`_ |
| 148 | + |
| 149 | + |
| 150 | +ChangeLog |
| 151 | +========= |
| 152 | + |
| 153 | +For version history and release notes, please visit |
| 154 | +`<https://wiki.qemu.org/ChangeLog/>`_ or look at the git history for |
| 155 | +more detailed information. |
| 156 | + |
| 157 | + |
| 158 | +Contact |
| 159 | +======= |
| 160 | + |
| 161 | +The QEMU community can be contacted in a number of ways, with the two |
| 162 | +main methods being email and IRC |
| 163 | + |
| 164 | + |
| 165 | +* `<https://lists.nongnu.org/mailman/listinfo/qemu-devel>`_ |
| 166 | +* #qemu on irc.oftc.net |
| 167 | + |
| 168 | +Information on additional methods of contacting the community can be |
| 169 | +found online via the QEMU website: |
| 170 | + |
| 171 | +* `<https://wiki.qemu.org/Contribute/StartHere>`_ |
0 commit comments