]>
Commit | Line | Data |
---|---|---|
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 | Building | |
35 | ======== | |
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 | ||
41 | ||
42 | .. code-block:: shell | |
43 | ||
44 | mkdir build | |
45 | cd build | |
46 | ../configure | |
47 | make | |
48 | ||
49 | Additional information can also be found online via the QEMU website: | |
50 | ||
51 | * `<https://qemu.org/Hosts/Linux>`_ | |
52 | * `<https://qemu.org/Hosts/Mac>`_ | |
53 | * `<https://qemu.org/Hosts/W32>`_ | |
54 | ||
55 | ||
56 | Submitting patches | |
57 | ================== | |
58 | ||
59 | The QEMU source code is maintained under the GIT version control system. | |
60 | ||
61 | .. code-block:: shell | |
62 | ||
63 | git clone https://git.qemu.org/git/qemu.git | |
64 | ||
65 | When submitting patches, one common approach is to use 'git | |
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 | |
69 | guidelines set out in the CODING_STYLE.rst file. | |
70 | ||
71 | Additional information on submitting patches can be found online via | |
72 | the QEMU website | |
73 | ||
74 | * `<https://qemu.org/Contribute/SubmitAPatch>`_ | |
75 | * `<https://qemu.org/Contribute/TrivialPatches>`_ | |
76 | ||
77 | The QEMU website is also maintained under source control. | |
78 | ||
79 | .. code-block:: shell | |
80 | ||
81 | git clone https://git.qemu.org/git/qemu-web.git | |
82 | ||
83 | * `<https://www.qemu.org/2017/02/04/the-new-qemu-website-is-up/>`_ | |
84 | ||
85 | A 'git-publish' utility was created to make above process less | |
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 | ||
94 | * `<https://github.com/stefanha/git-publish>`_ | |
95 | ||
96 | The workflow with 'git-publish' is: | |
97 | ||
98 | .. code-block:: shell | |
99 | ||
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 | ||
109 | .. code-block:: shell | |
110 | ||
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 | ||
118 | Bug reporting | |
119 | ============= | |
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 | ||
125 | * `<https://bugs.launchpad.net/qemu/>`_ | |
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 | ||
134 | * `<https://qemu.org/Contribute/ReportABug>`_ | |
135 | ||
136 | ||
137 | Contact | |
138 | ======= | |
139 | ||
140 | The QEMU community can be contacted in a number of ways, with the two | |
141 | main methods being email and IRC | |
142 | ||
143 | * `<mailto:qemu-devel@nongnu.org>`_ | |
144 | * `<https://lists.nongnu.org/mailman/listinfo/qemu-devel>`_ | |
145 | * #qemu on irc.oftc.net | |
146 | ||
147 | Information on additional methods of contacting the community can be | |
148 | found online via the QEMU website: | |
149 | ||
150 | * `<https://qemu.org/Contribute/StartHere>`_ |