]>
Commit | Line | Data |
---|---|---|
336a7451 DB |
1 | =========== |
2 | QEMU README | |
3 | =========== | |
3ef693a0 | 4 | |
0a3c1900 DB |
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 | Building | |
b95aae12 | 35 | ======== |
0a3c1900 DB |
36 | |
37 | QEMU is multi-platform software intended to be buildable on all modern | |
38 | Linux platforms, OS-X, Win32 (via the Mingw64 toolchain) and a variety | |
39 | of other UNIX targets. The simple steps to build QEMU are: | |
40 | ||
336a7451 DB |
41 | |
42 | .. code-block:: shell | |
43 | ||
b95aae12 PK |
44 | mkdir build |
45 | cd build | |
46 | ../configure | |
47 | make | |
0a3c1900 | 48 | |
0a3c1900 DB |
49 | Additional information can also be found online via the QEMU website: |
50 | ||
336a7451 DB |
51 | * `<https://qemu.org/Hosts/Linux>`_ |
52 | * `<https://qemu.org/Hosts/Mac>`_ | |
53 | * `<https://qemu.org/Hosts/W32>`_ | |
0a3c1900 DB |
54 | |
55 | ||
56 | Submitting patches | |
b95aae12 | 57 | ================== |
0a3c1900 DB |
58 | |
59 | The QEMU source code is maintained under the GIT version control system. | |
60 | ||
336a7451 DB |
61 | .. code-block:: shell |
62 | ||
c814b177 | 63 | git clone https://git.qemu.org/git/qemu.git |
0a3c1900 | 64 | |
23500c6a | 65 | When submitting patches, one common approach is to use 'git |
0a3c1900 DB |
66 | format-patch' and/or 'git send-email' to format & send the mail to the |
67 | qemu-devel@nongnu.org mailing list. All patches submitted must contain | |
68 | a 'Signed-off-by' line from the author. Patches should follow the | |
637f3956 | 69 | guidelines set out in the CODING_STYLE.rst file. |
0a3c1900 DB |
70 | |
71 | Additional information on submitting patches can be found online via | |
72 | the QEMU website | |
73 | ||
336a7451 DB |
74 | * `<https://qemu.org/Contribute/SubmitAPatch>`_ |
75 | * `<https://qemu.org/Contribute/TrivialPatches>`_ | |
0a3c1900 | 76 | |
a348f64d EB |
77 | The QEMU website is also maintained under source control. |
78 | ||
336a7451 DB |
79 | .. code-block:: shell |
80 | ||
c814b177 | 81 | git clone https://git.qemu.org/git/qemu-web.git |
336a7451 DB |
82 | |
83 | * `<https://www.qemu.org/2017/02/04/the-new-qemu-website-is-up/>`_ | |
0a3c1900 | 84 | |
7c9e2748 | 85 | A 'git-publish' utility was created to make above process less |
23500c6a FZ |
86 | cumbersome, and is highly recommended for making regular contributions, |
87 | or even just for sending consecutive patch series revisions. It also | |
88 | requires a working 'git send-email' setup, and by default doesn't | |
89 | automate everything, so you may want to go through the above steps | |
90 | manually for once. | |
91 | ||
92 | For installation instructions, please go to | |
93 | ||
336a7451 | 94 | * `<https://github.com/stefanha/git-publish>`_ |
23500c6a FZ |
95 | |
96 | The workflow with 'git-publish' is: | |
97 | ||
336a7451 DB |
98 | .. code-block:: shell |
99 | ||
23500c6a FZ |
100 | $ git checkout master -b my-feature |
101 | $ # work on new commits, add your 'Signed-off-by' lines to each | |
102 | $ git publish | |
103 | ||
104 | Your patch series will be sent and tagged as my-feature-v1 if you need to refer | |
105 | back to it in the future. | |
106 | ||
107 | Sending v2: | |
108 | ||
336a7451 DB |
109 | .. code-block:: shell |
110 | ||
23500c6a FZ |
111 | $ git checkout my-feature # same topic branch |
112 | $ # making changes to the commits (using 'git rebase', for example) | |
113 | $ git publish | |
114 | ||
115 | Your patch series will be sent with 'v2' tag in the subject and the git tip | |
116 | will be tagged as my-feature-v2. | |
117 | ||
0a3c1900 | 118 | Bug reporting |
b95aae12 | 119 | ============= |
0a3c1900 DB |
120 | |
121 | The QEMU project uses Launchpad as its primary upstream bug tracker. Bugs | |
122 | found when running code built from QEMU git or upstream released sources | |
123 | should be reported via: | |
124 | ||
336a7451 | 125 | * `<https://bugs.launchpad.net/qemu/>`_ |
0a3c1900 DB |
126 | |
127 | If using QEMU via an operating system vendor pre-built binary package, it | |
128 | is preferable to report bugs to the vendor's own bug tracker first. If | |
129 | the bug is also known to affect latest upstream code, it can also be | |
130 | reported via launchpad. | |
131 | ||
132 | For additional information on bug reporting consult: | |
133 | ||
336a7451 | 134 | * `<https://qemu.org/Contribute/ReportABug>`_ |
0a3c1900 DB |
135 | |
136 | ||
137 | Contact | |
b95aae12 | 138 | ======= |
0a3c1900 DB |
139 | |
140 | The QEMU community can be contacted in a number of ways, with the two | |
141 | main methods being email and IRC | |
142 | ||
336a7451 DB |
143 | * `<mailto:qemu-devel@nongnu.org>`_ |
144 | * `<https://lists.nongnu.org/mailman/listinfo/qemu-devel>`_ | |
145 | * #qemu on irc.oftc.net | |
0a3c1900 DB |
146 | |
147 | Information on additional methods of contacting the community can be | |
148 | found online via the QEMU website: | |
149 | ||
336a7451 | 150 | * `<https://qemu.org/Contribute/StartHere>`_ |