|
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 | | -qemu-devel@nongnu.org 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 | | -* `<mailto:qemu-devel@nongnu.org>`_ |
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>`_ |
| 1 | +This file must exists for ./scripts/checkpatch.pl to say it's a correct tree. |
0 commit comments