diff --git a/docs/docs.html.in b/docs/docs.html.in index c1741c89b418ed35f02f3b8f4d3bc9302bc131ec..6cf09f51bcc5d88d6dc0816e913a8d3e0750701c 100644 --- a/docs/docs.html.in +++ b/docs/docs.html.in @@ -128,6 +128,9 @@
Contributor guidelines
General hacking guidelines for contributors
+
Project strategy
+
Sets a vision for future direction & technical choices
+
Bug reports
How and where to report bugs and request features
diff --git a/docs/strategy.html.in b/docs/strategy.html.in new file mode 100644 index 0000000000000000000000000000000000000000..42c285d9f6aef207c7a74d303cb0e34e1c19cbc7 --- /dev/null +++ b/docs/strategy.html.in @@ -0,0 +1,146 @@ + + + + +

Project Strategy

+ +

+ This document attempts to outline the libvirt project strategy for + the near future. Think of this as a high level vision or to-do list + setting the direction for the project and its developers to take. +

+ +

Language consolidation

+ +

+ At time of writing libvirt uses the following languages: +

+ +
+
C
+
The core libvirt library, daemons, and helper tools are all written + in the C language.
+
Python
+
Various supporting build/test scripts are written in Python, with + compatibility for Python 2 and 3.
+
Perl
+
Various supporting build/test scripts are written in Perl. It is + also used for many syntax-check inline rules
+
Shell
+
configure, generated by autoconf, is a shell script. + Shell is also used for some simple build/test scripts. At runtime + libvirt avoids shell except when using SSH tunnels to a remote + host
+
XSLT
+
The website uses XSLT for its templating system. The API + documentation is also autogenerated from an XML description + using XSLT
+
HTML
+
The website documentation is all written in plain HTML. Some HTML + is also auto-generated for API documentation
+
M4
+
The autoconf configure script uses a large number of + M4 macros to generate its content
+
make
+
The core build system uses the traditional GNU make recipes
+
automake
+
The make recipes use automake's language extensions which are + then turned into regular make rules
+
awk/sed
+
A number of the syntax-check inline rules involve use of awk/sed + scripts
+
POD
+
The command line manual pages are typically written in Perl's POD + format, and converted to troff
+
+ +

+ The wide range of languages used present a knowledge burden for + developers involved in libvirt, especially when there are multiple + languages all used in the same problem spaces. This is most notable + in the build system which uses a combination of shell, M4, make, + automake, awk, sed, Perl and Python, with debugging requiring + understanding of the interactions between many languages. The + popularity of Perl has declined, while Python has become + more popular. This directly influences the amount and quality of + contributions that can be expected for programs written in the + respective languages. +

+

+ The C language has served libvirt well over the years, but its age shows + giving rise to limitations which negatively impact the project in terms + of code quality, reliability, and efficiency of development. Most notably + its lack of memory safety means that many code bugs become trivially + exploitable security flaws or denial of service. The lack of a high + level portable runtime results in a lot of effort being spent to + ensure cross platform portability. The modern languages Rust and Go + provide viable options for low level systems programming, in a way that + is not practical with other common languages such as Python and Java. + There is thus a desire to make use of either Rust or Go, or a combination + of both, to incrementally replace existing use of C, and also for + greenfield development. +

+

+ With this in mind the libvirt project has set a vision for language + usage in the future: +

+ +
+
C
+
Large parts of the core libvirt library, daemons, and helper tools + will continue to make use in the C language. Integration of other + languages will be an incremental, targetted process where they can + bring the greatest benefit.
+
Rust / Go
+
Parts of the core libvirt library, daemons and helper tools are to + leverage Rust or Go or both to replace C.
+
Meson
+
The core build system is to be written in Meson.
+
Python
+
Various supporting build/test scripts are written in Python 3 + compatible mode only.
+
reStructuredText
+
The website and command man pages are to be written in RST, using + Sphinx as the engine to convert to end user formats like HTML, troff, + etc
+
+ +

+ Some notable points from the above. Whether the core library / daemons + will use Rust or Go internally is still to be decided based on more + detailed evaluation to identify the best fit. The need to link and embed + this functionality in other processes has complex interactions both at a + technical and non-technical level. For standalone helper tools, either + language is viable, but there are fewer concerns around interactions with + other in-process code from 3rd parties. Thus a different decision may be + made for daemons/libraries vs tools. Any rewrite proposed for existing + functionality will have to weigh up the benefits of the new code, + against the risk of introducing regressions with respect to the previous + code. +

+ +

+ The Meson build system is written in Python 3. This directly informs the + choice of Python 3 as the language for all supporting build scripts, + re-inforcing the other benefits of Python over Perl, Shell, M4, + automake, etc. There is no intention to support Python 2 given Meson's + requirement for Python 3. +

+ +

+ Using the RST format for documentation allows for the use of XSLT to be + eliminated from the build process. RST and the Sphinx toolkit are widely + used, as seen by the huge repository of content on + Read The Docs. + The ability to embed raw HTML in the RST docs will greatly facilitate its + adoption, avoiding the need for a big bang conversion of existing content. + Given the desire to eliminate Perl usage, replacing the use of POD + documentation for manual pages is an obvious followup task. RST is the + obvious choice to achieve alignment with the website, allowing the man + pages to be easily published online with other docs. It is further + anticipated that the current API docs generator which uses XSLT to + convert the XML API description would be converted to something which + generates RST using Python instead of XSLT. +

+ +