[sdk/kdesrc-build] /: doc: Convert developer documentation to Markdown
Andrew Shark
null at kde.org
Thu Feb 8 08:05:47 GMT 2024
Git commit 469df9bbaf6e3d7c450e51d5981e95a9f5e1906a by Andrew Shark.
Committed on 08/02/2024 at 08:05.
Pushed by ashark into branch 'master'.
doc: Convert developer documentation to Markdown
- Move some documentation under doc
- Delete unneeded asciidoc instructions
- Delete some outdated files
D +0 -17 AUTHORS
D +0 -359 LICENSE
A +595 -0 LICENSE.md
D +0 -69 ROADMAP
M +0 -9 doc/CMakeLists.txt
D +0 -397 doc/COPYING.DOC
M +1 -24 doc/README.md
M +1 -2 doc/man-kdesrc-build.1.docbook
D +0 -22 doc/source-reference/CMakeLists.txt
A +243 -0 doc/source-reference/IPC-notes.md
D +0 -267 doc/source-reference/IPC-notes.pod
R +1 -1 doc/source-reference/Internals.md [from: Internals.txt - 099% similarity]
R +12 -12 doc/source-reference/Module.md [from: doc/source-reference/ksb/Module.adoc - 097% similarity]
D +0 -16 doc/source-reference/README
R +25 -29 doc/source-reference/index.md [from: doc/source-reference/index.adoc - 083% similarity]
D +0 -318 doc/source-reference/perl-upgrade-notes.pod
D +0 -181 doc/source-reference/serve-docs.pl
M +0 -17 modules/ksb.pm
https://invent.kde.org/sdk/kdesrc-build/-/commit/469df9bbaf6e3d7c450e51d5981e95a9f5e1906a
diff --git a/AUTHORS b/AUTHORS
deleted file mode 100644
index 436f10aa..00000000
--- a/AUTHORS
+++ /dev/null
@@ -1,17 +0,0 @@
-kdesrc-build was written by:
- Michael Pyne <mpyne at kde.org>
-
-Contributors include:
- David Faure <dfaure at kde.org>
- Thiago Macieira <thiago at kde.org>
- Dirk Mueller <dirk at kde.org>
- Stephen Kulow <coolo at kde.org>
- Raphael Kubo da Costa <rakuco at FreeBSD.org>
- Laurent Montel <montel at kde.org>
- Pino Toscano <pino at kde.org>
-
-Suggestions / improvements have been sent in from too many people to list! :)
-
-Documentation Gurus:
- Carlos Leonhard Woelz <carloswoelz at imap-mail.com>
- Michael Pyne <mpyne at kde.org>
diff --git a/LICENSE b/LICENSE
deleted file mode 100644
index 7762f91e..00000000
--- a/LICENSE
+++ /dev/null
@@ -1,359 +0,0 @@
-Note: The following license applies to all files in the kdesrc-build
-distribution unless otherwise noted in the file. You may use Version 2 or any
-later version of this license.
-
-Known exceptions:
-doc/build-docs - Licensed as stated in its header
- (BSD-style)
-doc/*.docbook - Licensed per KDE Documentation policy, i.e. under the
- GNU FDL v1.2 (or any later version), with no Invariant
- Sections, no Front-Cover Texts, and no Back-Cover Texts.
- Full text available as doc/COPYING.DOC
-modules/Mojo* - Licensed per the Artistic License 2.0, these modules
-modules/web are a stripped-down version of the Mojolicious upstream
- without source code modification, embedded with
- kdesrc-build. See https://github.com/mojolicious/mojo/
-
-License follows -------------------------------------------------------------
-
- GNU GENERAL PUBLIC LICENSE
- Version 2, June 1991
-
- Copyright (C) 1989, 1991 Free Software Foundation, Inc.
- 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
- Preamble
-
- The licenses for most software are designed to take away your
-freedom to share and change it. By contrast, the GNU General Public
-License is intended to guarantee your freedom to share and change free
-software--to make sure the software is free for all its users. This
-General Public License applies to most of the Free Software
-Foundation's software and to any other program whose authors commit to
-using it. (Some other Free Software Foundation software is covered by
-the GNU Library General Public License instead.) You can apply it to
-your programs, too.
-
- When we speak of free software, we are referring to freedom, not
-price. Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-this service if you wish), that you receive source code or can get it
-if you want it, that you can change the software or use pieces of it
-in new free programs; and that you know you can do these things.
-
- To protect your rights, we need to make restrictions that forbid
-anyone to deny you these rights or to ask you to surrender the rights.
-These restrictions translate to certain responsibilities for you if you
-distribute copies of the software, or if you modify it.
-
- For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must give the recipients all the rights that
-you have. You must make sure that they, too, receive or can get the
-source code. And you must show them these terms so they know their
-rights.
-
- We protect your rights with two steps: (1) copyright the software, and
-(2) offer you this license which gives you legal permission to copy,
-distribute and/or modify the software.
-
- Also, for each author's protection and ours, we want to make certain
-that everyone understands that there is no warranty for this free
-software. If the software is modified by someone else and passed on, we
-want its recipients to know that what they have is not the original, so
-that any problems introduced by others will not reflect on the original
-authors' reputations.
-
- Finally, any free program is threatened constantly by software
-patents. We wish to avoid the danger that redistributors of a free
-program will individually obtain patent licenses, in effect making the
-program proprietary. To prevent this, we have made it clear that any
-patent must be licensed for everyone's free use or not licensed at all.
-
- The precise terms and conditions for copying, distribution and
-modification follow.
-
- GNU GENERAL PUBLIC LICENSE
- TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
- 0. This License applies to any program or other work which contains
-a notice placed by the copyright holder saying it may be distributed
-under the terms of this General Public License. The "Program", below,
-refers to any such program or work, and a "work based on the Program"
-means either the Program or any derivative work under copyright law:
-that is to say, a work containing the Program or a portion of it,
-either verbatim or with modifications and/or translated into another
-language. (Hereinafter, translation is included without limitation in
-the term "modification".) Each licensee is addressed as "you".
-
-Activities other than copying, distribution and modification are not
-covered by this License; they are outside its scope. The act of
-running the Program is not restricted, and the output from the Program
-is covered only if its contents constitute a work based on the
-Program (independent of having been made by running the Program).
-Whether that is true depends on what the Program does.
-
- 1. You may copy and distribute verbatim copies of the Program's
-source code as you receive it, in any medium, provided that you
-conspicuously and appropriately publish on each copy an appropriate
-copyright notice and disclaimer of warranty; keep intact all the
-notices that refer to this License and to the absence of any warranty;
-and give any other recipients of the Program a copy of this License
-along with the Program.
-
-You may charge a fee for the physical act of transferring a copy, and
-you may at your option offer warranty protection in exchange for a fee.
-
- 2. You may modify your copy or copies of the Program or any portion
-of it, thus forming a work based on the Program, and copy and
-distribute such modifications or work under the terms of Section 1
-above, provided that you also meet all of these conditions:
-
- a) You must cause the modified files to carry prominent notices
- stating that you changed the files and the date of any change.
-
- b) You must cause any work that you distribute or publish, that in
- whole or in part contains or is derived from the Program or any
- part thereof, to be licensed as a whole at no charge to all third
- parties under the terms of this License.
-
- c) If the modified program normally reads commands interactively
- when run, you must cause it, when started running for such
- interactive use in the most ordinary way, to print or display an
- announcement including an appropriate copyright notice and a
- notice that there is no warranty (or else, saying that you provide
- a warranty) and that users may redistribute the program under
- these conditions, and telling the user how to view a copy of this
- License. (Exception: if the Program itself is interactive but
- does not normally print such an announcement, your work based on
- the Program is not required to print an announcement.)
-
-These requirements apply to the modified work as a whole. If
-identifiable sections of that work are not derived from the Program,
-and can be reasonably considered independent and separate works in
-themselves, then this License, and its terms, do not apply to those
-sections when you distribute them as separate works. But when you
-distribute the same sections as part of a whole which is a work based
-on the Program, the distribution of the whole must be on the terms of
-this License, whose permissions for other licensees extend to the
-entire whole, and thus to each and every part regardless of who wrote it.
-
-Thus, it is not the intent of this section to claim rights or contest
-your rights to work written entirely by you; rather, the intent is to
-exercise the right to control the distribution of derivative or
-collective works based on the Program.
-
-In addition, mere aggregation of another work not based on the Program
-with the Program (or with a work based on the Program) on a volume of
-a storage or distribution medium does not bring the other work under
-the scope of this License.
-
- 3. You may copy and distribute the Program (or a work based on it,
-under Section 2) in object code or executable form under the terms of
-Sections 1 and 2 above provided that you also do one of the following:
-
- a) Accompany it with the complete corresponding machine-readable
- source code, which must be distributed under the terms of Sections
- 1 and 2 above on a medium customarily used for software interchange; or,
-
- b) Accompany it with a written offer, valid for at least three
- years, to give any third party, for a charge no more than your
- cost of physically performing source distribution, a complete
- machine-readable copy of the corresponding source code, to be
- distributed under the terms of Sections 1 and 2 above on a medium
- customarily used for software interchange; or,
-
- c) Accompany it with the information you received as to the offer
- to distribute corresponding source code. (This alternative is
- allowed only for noncommercial distribution and only if you
- received the program in object code or executable form with such
- an offer, in accord with Subsection b above.)
-
-The source code for a work means the preferred form of the work for
-making modifications to it. For an executable work, complete source
-code means all the source code for all modules it contains, plus any
-associated interface definition files, plus the scripts used to
-control compilation and installation of the executable. However, as a
-special exception, the source code distributed need not include
-anything that is normally distributed (in either source or binary
-form) with the major components (compiler, kernel, and so on) of the
-operating system on which the executable runs, unless that component
-itself accompanies the executable.
-
-If distribution of executable or object code is made by offering
-access to copy from a designated place, then offering equivalent
-access to copy the source code from the same place counts as
-distribution of the source code, even though third parties are not
-compelled to copy the source along with the object code.
-
- 4. You may not copy, modify, sublicense, or distribute the Program
-except as expressly provided under this License. Any attempt
-otherwise to copy, modify, sublicense or distribute the Program is
-void, and will automatically terminate your rights under this License.
-However, parties who have received copies, or rights, from you under
-this License will not have their licenses terminated so long as such
-parties remain in full compliance.
-
- 5. You are not required to accept this License, since you have not
-signed it. However, nothing else grants you permission to modify or
-distribute the Program or its derivative works. These actions are
-prohibited by law if you do not accept this License. Therefore, by
-modifying or distributing the Program (or any work based on the
-Program), you indicate your acceptance of this License to do so, and
-all its terms and conditions for copying, distributing or modifying
-the Program or works based on it.
-
- 6. Each time you redistribute the Program (or any work based on the
-Program), the recipient automatically receives a license from the
-original licensor to copy, distribute or modify the Program subject to
-these terms and conditions. You may not impose any further
-restrictions on the recipients' exercise of the rights granted herein.
-You are not responsible for enforcing compliance by third parties to
-this License.
-
- 7. If, as a consequence of a court judgment or allegation of patent
-infringement or for any other reason (not limited to patent issues),
-conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License. If you cannot
-distribute so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you
-may not distribute the Program at all. For example, if a patent
-license would not permit royalty-free redistribution of the Program by
-all those who receive copies directly or indirectly through you, then
-the only way you could satisfy both it and this License would be to
-refrain entirely from distribution of the Program.
-
-If any portion of this section is held invalid or unenforceable under
-any particular circumstance, the balance of the section is intended to
-apply and the section as a whole is intended to apply in other
-circumstances.
-
-It is not the purpose of this section to induce you to infringe any
-patents or other property right claims or to contest validity of any
-such claims; this section has the sole purpose of protecting the
-integrity of the free software distribution system, which is
-implemented by public license practices. Many people have made
-generous contributions to the wide range of software distributed
-through that system in reliance on consistent application of that
-system; it is up to the author/donor to decide if he or she is willing
-to distribute software through any other system and a licensee cannot
-impose that choice.
-
-This section is intended to make thoroughly clear what is believed to
-be a consequence of the rest of this License.
-
- 8. If the distribution and/or use of the Program is restricted in
-certain countries either by patents or by copyrighted interfaces, the
-original copyright holder who places the Program under this License
-may add an explicit geographical distribution limitation excluding
-those countries, so that distribution is permitted only in or among
-countries not thus excluded. In such case, this License incorporates
-the limitation as if written in the body of this License.
-
- 9. The Free Software Foundation may publish revised and/or new versions
-of the General Public License from time to time. Such new versions will
-be similar in spirit to the present version, but may differ in detail to
-address new problems or concerns.
-
-Each version is given a distinguishing version number. If the Program
-specifies a version number of this License which applies to it and "any
-later version", you have the option of following the terms and conditions
-either of that version or of any later version published by the Free
-Software Foundation. If the Program does not specify a version number of
-this License, you may choose any version ever published by the Free Software
-Foundation.
-
- 10. If you wish to incorporate parts of the Program into other free
-programs whose distribution conditions are different, write to the author
-to ask for permission. For software which is copyrighted by the Free
-Software Foundation, write to the Free Software Foundation; we sometimes
-make exceptions for this. Our decision will be guided by the two goals
-of preserving the free status of all derivatives of our free software and
-of promoting the sharing and reuse of software generally.
-
- NO WARRANTY
-
- 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
-FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
-OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
-PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
-OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
-TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
-PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
-REPAIR OR CORRECTION.
-
- 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
-REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
-INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
-OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
-TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
-YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
-PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGES.
-
- END OF TERMS AND CONDITIONS
-
-
- How to Apply These Terms to Your New Programs
-
- If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
- To do so, attach the following notices to the program. It is safest
-to attach them to the start of each source file to most effectively
-convey the exclusion of warranty; and each file should have at least
-the "copyright" line and a pointer to where the full notice is found.
-
- <one line to give the program's name and a brief idea of what it does.>
- Copyright (C) 19yy <name of author>
-
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
- (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
-
-
-Also add information on how to contact you by electronic and paper mail.
-
-If the program is interactive, make it output a short notice like this
-when it starts in an interactive mode:
-
- Gnomovision version 69, Copyright (C) 19yy name of author
- Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
- This is free software, and you are welcome to redistribute it
- under certain conditions; type `show c' for details.
-
-The hypothetical commands `show w' and `show c' should show the appropriate
-parts of the General Public License. Of course, the commands you use may
-be called something other than `show w' and `show c'; they could even be
-mouse-clicks or menu items--whatever suits your program.
-
-You should also get your employer (if you work as a programmer) or your
-school, if any, to sign a "copyright disclaimer" for the program, if
-necessary. Here is a sample; alter the names:
-
- Yoyodyne, Inc., hereby disclaims all copyright interest in the program
- `Gnomovision' (which makes passes at compilers) written by James Hacker.
-
- <signature of Ty Coon>, 1 April 1989
- Ty Coon, President of Vice
-
-This General Public License does not permit incorporating your program into
-proprietary programs. If your program is a subroutine library, you may
-consider it more useful to permit linking proprietary applications with the
-library. If this is what you want to do, use the GNU Library General
-Public License instead of this License.
diff --git a/LICENSE.md b/LICENSE.md
new file mode 100644
index 00000000..840e2a45
--- /dev/null
+++ b/LICENSE.md
@@ -0,0 +1,595 @@
+GNU General Public License
+==========================
+
+_Version 3, 29 June 2007_
+_Copyright © 2007 Free Software Foundation, Inc. <<http://fsf.org/>>_
+
+Everyone is permitted to copy and distribute verbatim copies of this license
+document, but changing it is not allowed.
+
+## Preamble
+
+The GNU General Public License is a free, copyleft license for software and other
+kinds of works.
+
+The licenses for most software and other practical works are designed to take away
+your freedom to share and change the works. By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change all versions of a
+program--to make sure it remains free software for all its users. We, the Free
+Software Foundation, use the GNU General Public License for most of our software; it
+applies also to any other work released this way by its authors. You can apply it to
+your programs, too.
+
+When we speak of free software, we are referring to freedom, not price. Our General
+Public Licenses are designed to make sure that you have the freedom to distribute
+copies of free software (and charge for them if you wish), that you receive source
+code or can get it if you want it, that you can change the software or use pieces of
+it in new free programs, and that you know you can do these things.
+
+To protect your rights, we need to prevent others from denying you these rights or
+asking you to surrender the rights. Therefore, you have certain responsibilities if
+you distribute copies of the software, or if you modify it: responsibilities to
+respect the freedom of others.
+
+For example, if you distribute copies of such a program, whether gratis or for a fee,
+you must pass on to the recipients the same freedoms that you received. You must make
+sure that they, too, receive or can get the source code. And you must show them these
+terms so they know their rights.
+
+Developers that use the GNU GPL protect your rights with two steps: **(1)** assert
+copyright on the software, and **(2)** offer you this License giving you legal permission
+to copy, distribute and/or modify it.
+
+For the developers' and authors' protection, the GPL clearly explains that there is
+no warranty for this free software. For both users' and authors' sake, the GPL
+requires that modified versions be marked as changed, so that their problems will not
+be attributed erroneously to authors of previous versions.
+
+Some devices are designed to deny users access to install or run modified versions of
+the software inside them, although the manufacturer can do so. This is fundamentally
+incompatible with the aim of protecting users' freedom to change the software. The
+systematic pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable. Therefore, we have designed
+this version of the GPL to prohibit the practice for those products. If such problems
+arise substantially in other domains, we stand ready to extend this provision to
+those domains in future versions of the GPL, as needed to protect the freedom of
+users.
+
+Finally, every program is threatened constantly by software patents. States should
+not allow patents to restrict development and use of software on general-purpose
+computers, but in those that do, we wish to avoid the special danger that patents
+applied to a free program could make it effectively proprietary. To prevent this, the
+GPL assures that patents cannot be used to render the program non-free.
+
+The precise terms and conditions for copying, distribution and modification follow.
+
+## TERMS AND CONDITIONS
+
+### 0. Definitions
+
+“This License” refers to version 3 of the GNU General Public License.
+
+“Copyright” also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+“The Program” refers to any copyrightable work licensed under this
+License. Each licensee is addressed as “you”. “Licensees” and
+“recipients” may be individuals or organizations.
+
+To “modify” a work means to copy from or adapt all or part of the work in
+a fashion requiring copyright permission, other than the making of an exact copy. The
+resulting work is called a “modified version” of the earlier work or a
+work “based on” the earlier work.
+
+A “covered work” means either the unmodified Program or a work based on
+the Program.
+
+To “propagate” a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for infringement under
+applicable copyright law, except executing it on a computer or modifying a private
+copy. Propagation includes copying, distribution (with or without modification),
+making available to the public, and in some countries other activities as well.
+
+To “convey” a work means any kind of propagation that enables other
+parties to make or receive copies. Mere interaction with a user through a computer
+network, with no transfer of a copy, is not conveying.
+
+An interactive user interface displays “Appropriate Legal Notices” to the
+extent that it includes a convenient and prominently visible feature that **(1)**
+displays an appropriate copyright notice, and **(2)** tells the user that there is no
+warranty for the work (except to the extent that warranties are provided), that
+licensees may convey the work under this License, and how to view a copy of this
+License. If the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+### 1. Source Code
+
+The “source code” for a work means the preferred form of the work for
+making modifications to it. “Object code” means any non-source form of a
+work.
+
+A “Standard Interface” means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of interfaces
+specified for a particular programming language, one that is widely used among
+developers working in that language.
+
+The “System Libraries” of an executable work include anything, other than
+the work as a whole, that **(a)** is included in the normal form of packaging a Major
+Component, but which is not part of that Major Component, and **(b)** serves only to
+enable use of the work with that Major Component, or to implement a Standard
+Interface for which an implementation is available to the public in source code form.
+A “Major Component”, in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system (if any) on which
+the executable work runs, or a compiler used to produce the work, or an object code
+interpreter used to run it.
+
+The “Corresponding Source” for a work in object code form means all the
+source code needed to generate, install, and (for an executable work) run the object
+code and to modify the work, including scripts to control those activities. However,
+it does not include the work's System Libraries, or general-purpose tools or
+generally available free programs which are used unmodified in performing those
+activities but which are not part of the work. For example, Corresponding Source
+includes interface definition files associated with source files for the work, and
+the source code for shared libraries and dynamically linked subprograms that the work
+is specifically designed to require, such as by intimate data communication or
+control flow between those subprograms and other parts of the work.
+
+The Corresponding Source need not include anything that users can regenerate
+automatically from other parts of the Corresponding Source.
+
+The Corresponding Source for a work in source code form is that same work.
+
+### 2. Basic Permissions
+
+All rights granted under this License are granted for the term of copyright on the
+Program, and are irrevocable provided the stated conditions are met. This License
+explicitly affirms your unlimited permission to run the unmodified Program. The
+output from running a covered work is covered by this License only if the output,
+given its content, constitutes a covered work. This License acknowledges your rights
+of fair use or other equivalent, as provided by copyright law.
+
+You may make, run and propagate covered works that you do not convey, without
+conditions so long as your license otherwise remains in force. You may convey covered
+works to others for the sole purpose of having them make modifications exclusively
+for you, or provide you with facilities for running those works, provided that you
+comply with the terms of this License in conveying all material for which you do not
+control copyright. Those thus making or running the covered works for you must do so
+exclusively on your behalf, under your direction and control, on terms that prohibit
+them from making any copies of your copyrighted material outside their relationship
+with you.
+
+Conveying under any other circumstances is permitted solely under the conditions
+stated below. Sublicensing is not allowed; section 10 makes it unnecessary.
+
+### 3. Protecting Users' Legal Rights From Anti-Circumvention Law
+
+No covered work shall be deemed part of an effective technological measure under any
+applicable law fulfilling obligations under article 11 of the WIPO copyright treaty
+adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention
+of such measures.
+
+When you convey a covered work, you waive any legal power to forbid circumvention of
+technological measures to the extent such circumvention is effected by exercising
+rights under this License with respect to the covered work, and you disclaim any
+intention to limit operation or modification of the work as a means of enforcing,
+against the work's users, your or third parties' legal rights to forbid circumvention
+of technological measures.
+
+### 4. Conveying Verbatim Copies
+
+You may convey verbatim copies of the Program's source code as you receive it, in any
+medium, provided that you conspicuously and appropriately publish on each copy an
+appropriate copyright notice; keep intact all notices stating that this License and
+any non-permissive terms added in accord with section 7 apply to the code; keep
+intact all notices of the absence of any warranty; and give all recipients a copy of
+this License along with the Program.
+
+You may charge any price or no price for each copy that you convey, and you may offer
+support or warranty protection for a fee.
+
+### 5. Conveying Modified Source Versions
+
+You may convey a work based on the Program, or the modifications to produce it from
+the Program, in the form of source code under the terms of section 4, provided that
+you also meet all of these conditions:
+
+* **a)** The work must carry prominent notices stating that you modified it, and giving a
+ relevant date.
+* **b)** The work must carry prominent notices stating that it is released under this
+ License and any conditions added under section 7. This requirement modifies the
+ requirement in section 4 to “keep intact all notices”.
+* **c)** You must license the entire work, as a whole, under this License to anyone who
+ comes into possession of a copy. This License will therefore apply, along with any
+ applicable section 7 additional terms, to the whole of the work, and all its parts,
+ regardless of how they are packaged. This License gives no permission to license the
+ work in any other way, but it does not invalidate such permission if you have
+ separately received it.
+* **d)** If the work has interactive user interfaces, each must display Appropriate Legal
+ Notices; however, if the Program has interactive interfaces that do not display
+ Appropriate Legal Notices, your work need not make them do so.
+
+A compilation of a covered work with other separate and independent works, which are
+not by their nature extensions of the covered work, and which are not combined with
+it such as to form a larger program, in or on a volume of a storage or distribution
+medium, is called an “aggregate” if the compilation and its resulting
+copyright are not used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit. Inclusion of a covered work in an aggregate
+does not cause this License to apply to the other parts of the aggregate.
+
+### 6. Conveying Non-Source Forms
+
+You may convey a covered work in object code form under the terms of sections 4 and
+5, provided that you also convey the machine-readable Corresponding Source under the
+terms of this License, in one of these ways:
+
+* **a)** Convey the object code in, or embodied in, a physical product (including a
+ physical distribution medium), accompanied by the Corresponding Source fixed on a
+ durable physical medium customarily used for software interchange.
+* **b)** Convey the object code in, or embodied in, a physical product (including a
+ physical distribution medium), accompanied by a written offer, valid for at least
+ three years and valid for as long as you offer spare parts or customer support for
+ that product model, to give anyone who possesses the object code either **(1)** a copy of
+ the Corresponding Source for all the software in the product that is covered by this
+ License, on a durable physical medium customarily used for software interchange, for
+ a price no more than your reasonable cost of physically performing this conveying of
+ source, or **(2)** access to copy the Corresponding Source from a network server at no
+ charge.
+* **c)** Convey individual copies of the object code with a copy of the written offer to
+ provide the Corresponding Source. This alternative is allowed only occasionally and
+ noncommercially, and only if you received the object code with such an offer, in
+ accord with subsection 6b.
+* **d)** Convey the object code by offering access from a designated place (gratis or for
+ a charge), and offer equivalent access to the Corresponding Source in the same way
+ through the same place at no further charge. You need not require recipients to copy
+ the Corresponding Source along with the object code. If the place to copy the object
+ code is a network server, the Corresponding Source may be on a different server
+ (operated by you or a third party) that supports equivalent copying facilities,
+ provided you maintain clear directions next to the object code saying where to find
+ the Corresponding Source. Regardless of what server hosts the Corresponding Source,
+ you remain obligated to ensure that it is available for as long as needed to satisfy
+ these requirements.
+* **e)** Convey the object code using peer-to-peer transmission, provided you inform
+ other peers where the object code and Corresponding Source of the work are being
+ offered to the general public at no charge under subsection 6d.
+
+A separable portion of the object code, whose source code is excluded from the
+Corresponding Source as a System Library, need not be included in conveying the
+object code work.
+
+A “User Product” is either **(1)** a “consumer product”, which
+means any tangible personal property which is normally used for personal, family, or
+household purposes, or **(2)** anything designed or sold for incorporation into a
+dwelling. In determining whether a product is a consumer product, doubtful cases
+shall be resolved in favor of coverage. For a particular product received by a
+particular user, “normally used” refers to a typical or common use of
+that class of product, regardless of the status of the particular user or of the way
+in which the particular user actually uses, or expects or is expected to use, the
+product. A product is a consumer product regardless of whether the product has
+substantial commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+“Installation Information” for a User Product means any methods,
+procedures, authorization keys, or other information required to install and execute
+modified versions of a covered work in that User Product from a modified version of
+its Corresponding Source. The information must suffice to ensure that the continued
+functioning of the modified object code is in no case prevented or interfered with
+solely because modification has been made.
+
+If you convey an object code work under this section in, or with, or specifically for
+use in, a User Product, and the conveying occurs as part of a transaction in which
+the right of possession and use of the User Product is transferred to the recipient
+in perpetuity or for a fixed term (regardless of how the transaction is
+characterized), the Corresponding Source conveyed under this section must be
+accompanied by the Installation Information. But this requirement does not apply if
+neither you nor any third party retains the ability to install modified object code
+on the User Product (for example, the work has been installed in ROM).
+
+The requirement to provide Installation Information does not include a requirement to
+continue to provide support service, warranty, or updates for a work that has been
+modified or installed by the recipient, or for the User Product in which it has been
+modified or installed. Access to a network may be denied when the modification itself
+materially and adversely affects the operation of the network or violates the rules
+and protocols for communication across the network.
+
+Corresponding Source conveyed, and Installation Information provided, in accord with
+this section must be in a format that is publicly documented (and with an
+implementation available to the public in source code form), and must require no
+special password or key for unpacking, reading or copying.
+
+### 7. Additional Terms
+
+“Additional permissions” are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions. Additional
+permissions that are applicable to the entire Program shall be treated as though they
+were included in this License, to the extent that they are valid under applicable
+law. If additional permissions apply only to part of the Program, that part may be
+used separately under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+When you convey a copy of a covered work, you may at your option remove any
+additional permissions from that copy, or from any part of it. (Additional
+permissions may be written to require their own removal in certain cases when you
+modify the work.) You may place additional permissions on material, added by you to a
+covered work, for which you have or can give appropriate copyright permission.
+
+Notwithstanding any other provision of this License, for material you add to a
+covered work, you may (if authorized by the copyright holders of that material)
+supplement the terms of this License with terms:
+
+* **a)** Disclaiming warranty or limiting liability differently from the terms of
+ sections 15 and 16 of this License; or
+* **b)** Requiring preservation of specified reasonable legal notices or author
+ attributions in that material or in the Appropriate Legal Notices displayed by works
+ containing it; or
+* **c)** Prohibiting misrepresentation of the origin of that material, or requiring that
+ modified versions of such material be marked in reasonable ways as different from the
+ original version; or
+* **d)** Limiting the use for publicity purposes of names of licensors or authors of the
+ material; or
+* **e)** Declining to grant rights under trademark law for use of some trade names,
+ trademarks, or service marks; or
+* **f)** Requiring indemnification of licensors and authors of that material by anyone
+ who conveys the material (or modified versions of it) with contractual assumptions of
+ liability to the recipient, for any liability that these contractual assumptions
+ directly impose on those licensors and authors.
+
+All other non-permissive additional terms are considered “further
+restrictions” within the meaning of section 10. If the Program as you received
+it, or any part of it, contains a notice stating that it is governed by this License
+along with a term that is a further restriction, you may remove that term. If a
+license document contains a further restriction but permits relicensing or conveying
+under this License, you may add to a covered work material governed by the terms of
+that license document, provided that the further restriction does not survive such
+relicensing or conveying.
+
+If you add terms to a covered work in accord with this section, you must place, in
+the relevant source files, a statement of the additional terms that apply to those
+files, or a notice indicating where to find the applicable terms.
+
+Additional terms, permissive or non-permissive, may be stated in the form of a
+separately written license, or stated as exceptions; the above requirements apply
+either way.
+
+### 8. Termination
+
+You may not propagate or modify a covered work except as expressly provided under
+this License. Any attempt otherwise to propagate or modify it is void, and will
+automatically terminate your rights under this License (including any patent licenses
+granted under the third paragraph of section 11).
+
+However, if you cease all violation of this License, then your license from a
+particular copyright holder is reinstated **(a)** provisionally, unless and until the
+copyright holder explicitly and finally terminates your license, and **(b)** permanently,
+if the copyright holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is reinstated permanently
+if the copyright holder notifies you of the violation by some reasonable means, this
+is the first time you have received notice of violation of this License (for any
+work) from that copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the licenses of
+parties who have received copies or rights from you under this License. If your
+rights have been terminated and not permanently reinstated, you do not qualify to
+receive new licenses for the same material under section 10.
+
+### 9. Acceptance Not Required for Having Copies
+
+You are not required to accept this License in order to receive or run a copy of the
+Program. Ancillary propagation of a covered work occurring solely as a consequence of
+using peer-to-peer transmission to receive a copy likewise does not require
+acceptance. However, nothing other than this License grants you permission to
+propagate or modify any covered work. These actions infringe copyright if you do not
+accept this License. Therefore, by modifying or propagating a covered work, you
+indicate your acceptance of this License to do so.
+
+### 10. Automatic Licensing of Downstream Recipients
+
+Each time you convey a covered work, the recipient automatically receives a license
+from the original licensors, to run, modify and propagate that work, subject to this
+License. You are not responsible for enforcing compliance by third parties with this
+License.
+
+An “entity transaction” is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an organization, or
+merging organizations. If propagation of a covered work results from an entity
+transaction, each party to that transaction who receives a copy of the work also
+receives whatever licenses to the work the party's predecessor in interest had or
+could give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if the predecessor
+has it or can get it with reasonable efforts.
+
+You may not impose any further restrictions on the exercise of the rights granted or
+affirmed under this License. For example, you may not impose a license fee, royalty,
+or other charge for exercise of rights granted under this License, and you may not
+initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging
+that any patent claim is infringed by making, using, selling, offering for sale, or
+importing the Program or any portion of it.
+
+### 11. Patents
+
+A “contributor” is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based. The work thus
+licensed is called the contributor's “contributor version”.
+
+A contributor's “essential patent claims” are all patent claims owned or
+controlled by the contributor, whether already acquired or hereafter acquired, that
+would be infringed by some manner, permitted by this License, of making, using, or
+selling its contributor version, but do not include claims that would be infringed
+only as a consequence of further modification of the contributor version. For
+purposes of this definition, “control” includes the right to grant patent
+sublicenses in a manner consistent with the requirements of this License.
+
+Each contributor grants you a non-exclusive, worldwide, royalty-free patent license
+under the contributor's essential patent claims, to make, use, sell, offer for sale,
+import and otherwise run, modify and propagate the contents of its contributor
+version.
+
+In the following three paragraphs, a “patent license” is any express
+agreement or commitment, however denominated, not to enforce a patent (such as an
+express permission to practice a patent or covenant not to sue for patent
+infringement). To “grant” such a patent license to a party means to make
+such an agreement or commitment not to enforce a patent against the party.
+
+If you convey a covered work, knowingly relying on a patent license, and the
+Corresponding Source of the work is not available for anyone to copy, free of charge
+and under the terms of this License, through a publicly available network server or
+other readily accessible means, then you must either **(1)** cause the Corresponding
+Source to be so available, or **(2)** arrange to deprive yourself of the benefit of the
+patent license for this particular work, or **(3)** arrange, in a manner consistent with
+the requirements of this License, to extend the patent license to downstream
+recipients. “Knowingly relying” means you have actual knowledge that, but
+for the patent license, your conveying the covered work in a country, or your
+recipient's use of the covered work in a country, would infringe one or more
+identifiable patents in that country that you have reason to believe are valid.
+
+If, pursuant to or in connection with a single transaction or arrangement, you
+convey, or propagate by procuring conveyance of, a covered work, and grant a patent
+license to some of the parties receiving the covered work authorizing them to use,
+propagate, modify or convey a specific copy of the covered work, then the patent
+license you grant is automatically extended to all recipients of the covered work and
+works based on it.
+
+A patent license is “discriminatory” if it does not include within the
+scope of its coverage, prohibits the exercise of, or is conditioned on the
+non-exercise of one or more of the rights that are specifically granted under this
+License. You may not convey a covered work if you are a party to an arrangement with
+a third party that is in the business of distributing software, under which you make
+payment to the third party based on the extent of your activity of conveying the
+work, and under which the third party grants, to any of the parties who would receive
+the covered work from you, a discriminatory patent license **(a)** in connection with
+copies of the covered work conveyed by you (or copies made from those copies), or **(b)**
+primarily for and in connection with specific products or compilations that contain
+the covered work, unless you entered into that arrangement, or that patent license
+was granted, prior to 28 March 2007.
+
+Nothing in this License shall be construed as excluding or limiting any implied
+license or other defenses to infringement that may otherwise be available to you
+under applicable patent law.
+
+### 12. No Surrender of Others' Freedom
+
+If conditions are imposed on you (whether by court order, agreement or otherwise)
+that contradict the conditions of this License, they do not excuse you from the
+conditions of this License. If you cannot convey a covered work so as to satisfy
+simultaneously your obligations under this License and any other pertinent
+obligations, then as a consequence you may not convey it at all. For example, if you
+agree to terms that obligate you to collect a royalty for further conveying from
+those to whom you convey the Program, the only way you could satisfy both those terms
+and this License would be to refrain entirely from conveying the Program.
+
+### 13. Use with the GNU Affero General Public License
+
+Notwithstanding any other provision of this License, you have permission to link or
+combine any covered work with a work licensed under version 3 of the GNU Affero
+General Public License into a single combined work, and to convey the resulting work.
+The terms of this License will continue to apply to the part which is the covered
+work, but the special requirements of the GNU Affero General Public License, section
+13, concerning interaction through a network will apply to the combination as such.
+
+### 14. Revised Versions of this License
+
+The Free Software Foundation may publish revised and/or new versions of the GNU
+General Public License from time to time. Such new versions will be similar in spirit
+to the present version, but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program specifies that
+a certain numbered version of the GNU General Public License “or any later
+version” applies to it, you have the option of following the terms and
+conditions either of that numbered version or of any later version published by the
+Free Software Foundation. If the Program does not specify a version number of the GNU
+General Public License, you may choose any version ever published by the Free
+Software Foundation.
+
+If the Program specifies that a proxy can decide which future versions of the GNU
+General Public License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the Program.
+
+Later license versions may give you additional or different permissions. However, no
+additional obligations are imposed on any author or copyright holder as a result of
+your choosing to follow a later version.
+
+### 15. Disclaimer of Warranty
+
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
+EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
+QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
+DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+### 16. Limitation of Liability
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY
+COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS
+PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
+INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE
+OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
+WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+### 17. Interpretation of Sections 15 and 16
+
+If the disclaimer of warranty and limitation of liability provided above cannot be
+given local legal effect according to their terms, reviewing courts shall apply local
+law that most closely approximates an absolute waiver of all civil liability in
+connection with the Program, unless a warranty or assumption of liability accompanies
+a copy of the Program in return for a fee.
+
+_END OF TERMS AND CONDITIONS_
+
+## How to Apply These Terms to Your New Programs
+
+If you develop a new program, and you want it to be of the greatest possible use to
+the public, the best way to achieve this is to make it free software which everyone
+can redistribute and change under these terms.
+
+To do so, attach the following notices to the program. It is safest to attach them
+to the start of each source file to most effectively state the exclusion of warranty;
+and each file should have at least the “copyright” line and a pointer to
+where the full notice is found.
+
+ <one line to give the program's name and a brief idea of what it does.>
+ Copyright (C) <year> <name of author>
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program does terminal interaction, make it output a short notice like this
+when it starts in an interactive mode:
+
+ <program> Copyright (C) <year> <name of author>
+ This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
+ This is free software, and you are welcome to redistribute it
+ under certain conditions; type 'show c' for details.
+
+The hypothetical commands `show w` and `show c` should show the appropriate parts of
+the General Public License. Of course, your program's commands might be different;
+for a GUI interface, you would use an “about box”.
+
+You should also get your employer (if you work as a programmer) or school, if any, to
+sign a “copyright disclaimer” for the program, if necessary. For more
+information on this, and how to apply and follow the GNU GPL, see
+<<http://www.gnu.org/licenses/>>.
+
+The GNU General Public License does not permit incorporating your program into
+proprietary programs. If your program is a subroutine library, you may consider it
+more useful to permit linking proprietary applications with the library. If this is
+what you want to do, use the GNU Lesser General Public License instead of this
+License. But first, please read
+<<http://www.gnu.org/philosophy/why-not-lgpl.html>>.
\ No newline at end of file
diff --git a/ROADMAP b/ROADMAP
deleted file mode 100644
index f7852a6a..00000000
--- a/ROADMAP
+++ /dev/null
@@ -1,69 +0,0 @@
-The Roadmap
------------
-
-This is a list of the changes that I would like to have made in the upcoming
-versions, as of 2012-05-06. Unfortunately I can't give a good timeframe:
-
-1. Further modularization. This is to support enhancing the test suite by
-having clear boundaries between components and better-defined requirements for
-integration of those components.
-
-1a. Specifically, move git-related code to GitUpdate. DONE.
-
-2. Make the changes necessary to build Qt 5.
-
-3. Better documentation. Even if this means having a Markdown-to-DocBook
-converter, it would be much nicer to have documentation that was at least
-semi-consistent with the current state of building KDE software.
-
-4. Reduced duplication.
-
-4a. Remove support for "built-in" modules entirely, instead
-fallback to a kdesrc-buildrc hosted on KDE's git infrastructure if the user
-doesn't define one. DONE.
-
-4b. The kdesrc-buildrc-setup should be able to use this
-fallback kdesrc-buildrc as well when offering options.
-
-5. Generate `.xsession`/`.bashrc`/`.bash_profile` entries. i.e. make it
-possible for the environment variables needed to _run_ the installed KDE
-software be automatically setup by kdesrc-build, either by generating the
-appropriate rc files or by using kdesrc-build as a trampoline (e.g.
-kdesrc-build --launch startkde). DONE (2012-11-21, see xsession: commits)
-
-6. Test suite. Should be self-explanatory but the test suite can be far better
-than it is now. Probably should go Perl-style and split the large
-kdesrc-build-test.pl into a t/*.pl containing unit tests and whatever
-integration tests can be cooked up. But then again, it's not like we're
-launching astronauts into space, so don't go overboard.
-
-7. A distro-specific "auto packager" script. I.e. some way to say "install the
-base dependencies that are expected to be provided by the system" and have it
-kept up-to-date by volunteers using each distro (not that I'd hold my breath,
-but it has to be better than what we have now)
-
-8. Improved output. The current output, even in --verbose, is very noisy.
-Instead a "dashboard" approach would be better (for ncurses). It would be nice
-to support GUI output if a GUI is available but it should remain optional to
-support headless installs.
-
-9. "Network install". Right now kdesrc-build is a single-script install that
-tries to rely only on Perl 5.10 core modules + LWP. Instead the single script
-should be a shell that downloads Perl modules of kdesrc-build as needed from
-anongit. We would need to investigate how to ensure this is cryptographically
-safe for users, or if this is already assured by the git SCM.
-
-10. Continue porting code to standard Perl modules. Probably the biggest
-"problem child" to go next would be the process_arguments subroutine which
-really needs to be handled by a Getopt-alike.
-
-11. System reporting tool for reporting bugs. Possibly even using XML-RPC to
-post bug to bugs.kde.org automatically (or at least launch the wizard right).
-
-12. Use CPAN. Although I've been trying to keep kdesrc-build a kind of
-hyper-documented Perl, this hasn't helped a great deal with code contribution.
-It would be nice to be able to use some CPAN modules but I don't want to
-require they be installed beforehand. Having a way to download from CPAN
-automatically and save to the kdesrc-build working directories would solve this
-but again would need to look into how to mark whether a given CPAN module has
-been tested by the KDE developers...
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 603d4b35..c95d0b2b 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -3,12 +3,3 @@ kdoctools_create_handbook(index.docbook INSTALL_DESTINATION ${KDE_INSTALL_DOCBUN
kdoctools_create_manpage(man-kdesrc-build.1.docbook 1 INSTALL_DESTINATION ${MAN_INSTALL_DIR})
install(PROGRAMS kdesrc-build.desktop DESTINATION ${KDE_INSTALL_APPDIR})
-
-# Look for asciidoctor for source reference
-find_program(ASCIIDOCTOR_PATH asciidoctor)
-
-if (ASCIIDOCTOR_PATH)
- add_subdirectory(source-reference)
-else()
- message(STATUS "Could not find asciidoctor, will not build developer source reference")
-endif()
diff --git a/doc/COPYING.DOC b/doc/COPYING.DOC
deleted file mode 100644
index 4a0fe1c8..00000000
--- a/doc/COPYING.DOC
+++ /dev/null
@@ -1,397 +0,0 @@
- GNU Free Documentation License
- Version 1.2, November 2002
-
-
- Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-
-0. PREAMBLE
-
-The purpose of this License is to make a manual, textbook, or other
-functional and useful document "free" in the sense of freedom: to
-assure everyone the effective freedom to copy and redistribute it,
-with or without modifying it, either commercially or noncommercially.
-Secondarily, this License preserves for the author and publisher a way
-to get credit for their work, while not being considered responsible
-for modifications made by others.
-
-This License is a kind of "copyleft", which means that derivative
-works of the document must themselves be free in the same sense. It
-complements the GNU General Public License, which is a copyleft
-license designed for free software.
-
-We have designed this License in order to use it for manuals for free
-software, because free software needs free documentation: a free
-program should come with manuals providing the same freedoms that the
-software does. But this License is not limited to software manuals;
-it can be used for any textual work, regardless of subject matter or
-whether it is published as a printed book. We recommend this License
-principally for works whose purpose is instruction or reference.
-
-
-1. APPLICABILITY AND DEFINITIONS
-
-This License applies to any manual or other work, in any medium, that
-contains a notice placed by the copyright holder saying it can be
-distributed under the terms of this License. Such a notice grants a
-world-wide, royalty-free license, unlimited in duration, to use that
-work under the conditions stated herein. The "Document", below,
-refers to any such manual or work. Any member of the public is a
-licensee, and is addressed as "you". You accept the license if you
-copy, modify or distribute the work in a way requiring permission
-under copyright law.
-
-A "Modified Version" of the Document means any work containing the
-Document or a portion of it, either copied verbatim, or with
-modifications and/or translated into another language.
-
-A "Secondary Section" is a named appendix or a front-matter section of
-the Document that deals exclusively with the relationship of the
-publishers or authors of the Document to the Document's overall subject
-(or to related matters) and contains nothing that could fall directly
-within that overall subject. (Thus, if the Document is in part a
-textbook of mathematics, a Secondary Section may not explain any
-mathematics.) The relationship could be a matter of historical
-connection with the subject or with related matters, or of legal,
-commercial, philosophical, ethical or political position regarding
-them.
-
-The "Invariant Sections" are certain Secondary Sections whose titles
-are designated, as being those of Invariant Sections, in the notice
-that says that the Document is released under this License. If a
-section does not fit the above definition of Secondary then it is not
-allowed to be designated as Invariant. The Document may contain zero
-Invariant Sections. If the Document does not identify any Invariant
-Sections then there are none.
-
-The "Cover Texts" are certain short passages of text that are listed,
-as Front-Cover Texts or Back-Cover Texts, in the notice that says that
-the Document is released under this License. A Front-Cover Text may
-be at most 5 words, and a Back-Cover Text may be at most 25 words.
-
-A "Transparent" copy of the Document means a machine-readable copy,
-represented in a format whose specification is available to the
-general public, that is suitable for revising the document
-straightforwardly with generic text editors or (for images composed of
-pixels) generic paint programs or (for drawings) some widely available
-drawing editor, and that is suitable for input to text formatters or
-for automatic translation to a variety of formats suitable for input
-to text formatters. A copy made in an otherwise Transparent file
-format whose markup, or absence of markup, has been arranged to thwart
-or discourage subsequent modification by readers is not Transparent.
-An image format is not Transparent if used for any substantial amount
-of text. A copy that is not "Transparent" is called "Opaque".
-
-Examples of suitable formats for Transparent copies include plain
-ASCII without markup, Texinfo input format, LaTeX input format, SGML
-or XML using a publicly available DTD, and standard-conforming simple
-HTML, PostScript or PDF designed for human modification. Examples of
-transparent image formats include PNG, XCF and JPG. Opaque formats
-include proprietary formats that can be read and edited only by
-proprietary word processors, SGML or XML for which the DTD and/or
-processing tools are not generally available, and the
-machine-generated HTML, PostScript or PDF produced by some word
-processors for output purposes only.
-
-The "Title Page" means, for a printed book, the title page itself,
-plus such following pages as are needed to hold, legibly, the material
-this License requires to appear in the title page. For works in
-formats which do not have any title page as such, "Title Page" means
-the text near the most prominent appearance of the work's title,
-preceding the beginning of the body of the text.
-
-A section "Entitled XYZ" means a named subunit of the Document whose
-title either is precisely XYZ or contains XYZ in parentheses following
-text that translates XYZ in another language. (Here XYZ stands for a
-specific section name mentioned below, such as "Acknowledgements",
-"Dedications", "Endorsements", or "History".) To "Preserve the Title"
-of such a section when you modify the Document means that it remains a
-section "Entitled XYZ" according to this definition.
-
-The Document may include Warranty Disclaimers next to the notice which
-states that this License applies to the Document. These Warranty
-Disclaimers are considered to be included by reference in this
-License, but only as regards disclaiming warranties: any other
-implication that these Warranty Disclaimers may have is void and has
-no effect on the meaning of this License.
-
-
-2. VERBATIM COPYING
-
-You may copy and distribute the Document in any medium, either
-commercially or noncommercially, provided that this License, the
-copyright notices, and the license notice saying this License applies
-to the Document are reproduced in all copies, and that you add no other
-conditions whatsoever to those of this License. You may not use
-technical measures to obstruct or control the reading or further
-copying of the copies you make or distribute. However, you may accept
-compensation in exchange for copies. If you distribute a large enough
-number of copies you must also follow the conditions in section 3.
-
-You may also lend copies, under the same conditions stated above, and
-you may publicly display copies.
-
-
-3. COPYING IN QUANTITY
-
-If you publish printed copies (or copies in media that commonly have
-printed covers) of the Document, numbering more than 100, and the
-Document's license notice requires Cover Texts, you must enclose the
-copies in covers that carry, clearly and legibly, all these Cover
-Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
-the back cover. Both covers must also clearly and legibly identify
-you as the publisher of these copies. The front cover must present
-the full title with all words of the title equally prominent and
-visible. You may add other material on the covers in addition.
-Copying with changes limited to the covers, as long as they preserve
-the title of the Document and satisfy these conditions, can be treated
-as verbatim copying in other respects.
-
-If the required texts for either cover are too voluminous to fit
-legibly, you should put the first ones listed (as many as fit
-reasonably) on the actual cover, and continue the rest onto adjacent
-pages.
-
-If you publish or distribute Opaque copies of the Document numbering
-more than 100, you must either include a machine-readable Transparent
-copy along with each Opaque copy, or state in or with each Opaque copy
-a computer-network location from which the general network-using
-public has access to download using public-standard network protocols
-a complete Transparent copy of the Document, free of added material.
-If you use the latter option, you must take reasonably prudent steps,
-when you begin distribution of Opaque copies in quantity, to ensure
-that this Transparent copy will remain thus accessible at the stated
-location until at least one year after the last time you distribute an
-Opaque copy (directly or through your agents or retailers) of that
-edition to the public.
-
-It is requested, but not required, that you contact the authors of the
-Document well before redistributing any large number of copies, to give
-them a chance to provide you with an updated version of the Document.
-
-
-4. MODIFICATIONS
-
-You may copy and distribute a Modified Version of the Document under
-the conditions of sections 2 and 3 above, provided that you release
-the Modified Version under precisely this License, with the Modified
-Version filling the role of the Document, thus licensing distribution
-and modification of the Modified Version to whoever possesses a copy
-of it. In addition, you must do these things in the Modified Version:
-
-A. Use in the Title Page (and on the covers, if any) a title distinct
- from that of the Document, and from those of previous versions
- (which should, if there were any, be listed in the History section
- of the Document). You may use the same title as a previous version
- if the original publisher of that version gives permission.
-B. List on the Title Page, as authors, one or more persons or entities
- responsible for authorship of the modifications in the Modified
- Version, together with at least five of the principal authors of the
- Document (all of its principal authors, if it has fewer than five),
- unless they release you from this requirement.
-C. State on the Title page the name of the publisher of the
- Modified Version, as the publisher.
-D. Preserve all the copyright notices of the Document.
-E. Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
-F. Include, immediately after the copyright notices, a license notice
- giving the public permission to use the Modified Version under the
- terms of this License, in the form shown in the Addendum below.
-G. Preserve in that license notice the full lists of Invariant Sections
- and required Cover Texts given in the Document's license notice.
-H. Include an unaltered copy of this License.
-I. Preserve the section Entitled "History", Preserve its Title, and add
- to it an item stating at least the title, year, new authors, and
- publisher of the Modified Version as given on the Title Page. If
- there is no section Entitled "History" in the Document, create one
- stating the title, year, authors, and publisher of the Document as
- given on its Title Page, then add an item describing the Modified
- Version as stated in the previous sentence.
-J. Preserve the network location, if any, given in the Document for
- public access to a Transparent copy of the Document, and likewise
- the network locations given in the Document for previous versions
- it was based on. These may be placed in the "History" section.
- You may omit a network location for a work that was published at
- least four years before the Document itself, or if the original
- publisher of the version it refers to gives permission.
-K. For any section Entitled "Acknowledgements" or "Dedications",
- Preserve the Title of the section, and preserve in the section all
- the substance and tone of each of the contributor acknowledgements
- and/or dedications given therein.
-L. Preserve all the Invariant Sections of the Document,
- unaltered in their text and in their titles. Section numbers
- or the equivalent are not considered part of the section titles.
-M. Delete any section Entitled "Endorsements". Such a section
- may not be included in the Modified Version.
-N. Do not retitle any existing section to be Entitled "Endorsements"
- or to conflict in title with any Invariant Section.
-O. Preserve any Warranty Disclaimers.
-
-If the Modified Version includes new front-matter sections or
-appendices that qualify as Secondary Sections and contain no material
-copied from the Document, you may at your option designate some or all
-of these sections as invariant. To do this, add their titles to the
-list of Invariant Sections in the Modified Version's license notice.
-These titles must be distinct from any other section titles.
-
-You may add a section Entitled "Endorsements", provided it contains
-nothing but endorsements of your Modified Version by various
-parties--for example, statements of peer review or that the text has
-been approved by an organization as the authoritative definition of a
-standard.
-
-You may add a passage of up to five words as a Front-Cover Text, and a
-passage of up to 25 words as a Back-Cover Text, to the end of the list
-of Cover Texts in the Modified Version. Only one passage of
-Front-Cover Text and one of Back-Cover Text may be added by (or
-through arrangements made by) any one entity. If the Document already
-includes a cover text for the same cover, previously added by you or
-by arrangement made by the same entity you are acting on behalf of,
-you may not add another; but you may replace the old one, on explicit
-permission from the previous publisher that added the old one.
-
-The author(s) and publisher(s) of the Document do not by this License
-give permission to use their names for publicity for or to assert or
-imply endorsement of any Modified Version.
-
-
-5. COMBINING DOCUMENTS
-
-You may combine the Document with other documents released under this
-License, under the terms defined in section 4 above for modified
-versions, provided that you include in the combination all of the
-Invariant Sections of all of the original documents, unmodified, and
-list them all as Invariant Sections of your combined work in its
-license notice, and that you preserve all their Warranty Disclaimers.
-
-The combined work need only contain one copy of this License, and
-multiple identical Invariant Sections may be replaced with a single
-copy. If there are multiple Invariant Sections with the same name but
-different contents, make the title of each such section unique by
-adding at the end of it, in parentheses, the name of the original
-author or publisher of that section if known, or else a unique number.
-Make the same adjustment to the section titles in the list of
-Invariant Sections in the license notice of the combined work.
-
-In the combination, you must combine any sections Entitled "History"
-in the various original documents, forming one section Entitled
-"History"; likewise combine any sections Entitled "Acknowledgements",
-and any sections Entitled "Dedications". You must delete all sections
-Entitled "Endorsements".
-
-
-6. COLLECTIONS OF DOCUMENTS
-
-You may make a collection consisting of the Document and other documents
-released under this License, and replace the individual copies of this
-License in the various documents with a single copy that is included in
-the collection, provided that you follow the rules of this License for
-verbatim copying of each of the documents in all other respects.
-
-You may extract a single document from such a collection, and distribute
-it individually under this License, provided you insert a copy of this
-License into the extracted document, and follow this License in all
-other respects regarding verbatim copying of that document.
-
-
-7. AGGREGATION WITH INDEPENDENT WORKS
-
-A compilation of the Document or its derivatives with other separate
-and independent documents or works, in or on a volume of a storage or
-distribution medium, is called an "aggregate" if the copyright
-resulting from the compilation is not used to limit the legal rights
-of the compilation's users beyond what the individual works permit.
-When the Document is included in an aggregate, this License does not
-apply to the other works in the aggregate which are not themselves
-derivative works of the Document.
-
-If the Cover Text requirement of section 3 is applicable to these
-copies of the Document, then if the Document is less than one half of
-the entire aggregate, the Document's Cover Texts may be placed on
-covers that bracket the Document within the aggregate, or the
-electronic equivalent of covers if the Document is in electronic form.
-Otherwise they must appear on printed covers that bracket the whole
-aggregate.
-
-
-8. TRANSLATION
-
-Translation is considered a kind of modification, so you may
-distribute translations of the Document under the terms of section 4.
-Replacing Invariant Sections with translations requires special
-permission from their copyright holders, but you may include
-translations of some or all Invariant Sections in addition to the
-original versions of these Invariant Sections. You may include a
-translation of this License, and all the license notices in the
-Document, and any Warranty Disclaimers, provided that you also include
-the original English version of this License and the original versions
-of those notices and disclaimers. In case of a disagreement between
-the translation and the original version of this License or a notice
-or disclaimer, the original version will prevail.
-
-If a section in the Document is Entitled "Acknowledgements",
-"Dedications", or "History", the requirement (section 4) to Preserve
-its Title (section 1) will typically require changing the actual
-title.
-
-
-9. TERMINATION
-
-You may not copy, modify, sublicense, or distribute the Document except
-as expressly provided for under this License. Any other attempt to
-copy, modify, sublicense or distribute the Document is void, and will
-automatically terminate your rights under this License. However,
-parties who have received copies, or rights, from you under this
-License will not have their licenses terminated so long as such
-parties remain in full compliance.
-
-
-10. FUTURE REVISIONS OF THIS LICENSE
-
-The Free Software Foundation may publish new, revised versions
-of the GNU Free Documentation License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns. See
-http://www.gnu.org/copyleft/.
-
-Each version of the License is given a distinguishing version number.
-If the Document specifies that a particular numbered version of this
-License "or any later version" applies to it, you have the option of
-following the terms and conditions either of that specified version or
-of any later version that has been published (not as a draft) by the
-Free Software Foundation. If the Document does not specify a version
-number of this License, you may choose any version ever published (not
-as a draft) by the Free Software Foundation.
-
-
-ADDENDUM: How to use this License for your documents
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and
-license notices just after the title page:
-
- Copyright (c) YEAR YOUR NAME.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.2
- or any later version published by the Free Software Foundation;
- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
- A copy of the license is included in the section entitled "GNU
- Free Documentation License".
-
-If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
-replace the "with...Texts." line with this:
-
- with the Invariant Sections being LIST THEIR TITLES, with the
- Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
-
-If you have Invariant Sections without Cover Texts, or some other
-combination of the three, merge those two alternatives to suit the
-situation.
-
-If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License,
-to permit their use in free software.
diff --git a/doc/README.md b/doc/README.md
index e6c60812..0c846677 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -40,30 +40,7 @@ not available.
Documentation for kdesrc-build itself is mostly within the source files, but I've put
scattered attempts together over time trying to improve that.
-### POD format docs
-
-I think I've settled on using [Perl's "POD"
-format](https://perldoc.perl.org/perlpodspec) for documentation, even though
-it's awful, simply because that's the best way to integrate the documentation
-as close to the source code as possible.
-
-See the source-reference/serve-docs.pl script (which requires
-[Mojolicious](https://metacpan.org/pod/Mojolicious) and
-[Mojolicious::Plugin::PODViewer](https://metacpan.org/pod/Mojolicious::Plugin::PODViewer)
-to be installed from CPAN. I recommend
-[cpanminus](https://metacpan.org/pod/App::cpanminus) to handle CPAN management
-unless you are used to something else.
-
-### Older docs
-
-Older bits of documentation including `Internals.txt` (at the repository root)
-and AsciiDoc-based documentation (in doc/source-reference) are likely still
-helpful even though they're older, as the source has not drastically changed
-over the years.
-
-The AsciiDoc documentation in doc/source-reference has a CMakeLists.txt command
-in that directory to build the documentation, assuming you have
-[Asciidoctor](https://asciidoctor.org/) installed.
+Older bits of documentation can be found in source-reference directory.
## kdesrc-build Tricks
diff --git a/doc/man-kdesrc-build.1.docbook b/doc/man-kdesrc-build.1.docbook
index 6556b358..3fa71162 100644
--- a/doc/man-kdesrc-build.1.docbook
+++ b/doc/man-kdesrc-build.1.docbook
@@ -11,8 +11,7 @@
Permission is granted to copy, distribute and/or modify this document under
the terms of the GNU Free Documentation License, Version 1.2 or any later
version published by the Free Software Foundation; with no Invariant
- Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the
- license is included in COPYING.DOC.
+ Sections, no Front-Cover Texts, and no Back-Cover Texts.
-->
<refentry lang="&language;">
diff --git a/doc/source-reference/CMakeLists.txt b/doc/source-reference/CMakeLists.txt
deleted file mode 100644
index bcb2ab71..00000000
--- a/doc/source-reference/CMakeLists.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-SET(ASCIIDOCTOR_SOURCES
- index.adoc
- ksb/Module.adoc
- )
-
-# Disable use of external resources by default in the stylesheet
-SET(ASCIIDOCTOR_OPTS -a 'webfonts!')
-
-# The most proper way to do this is to have each *.html file individually
-# depend upon its *.adoc file, but asciidoctor is quick enough to just
-# re-build everything each time any of those files change.
-list(TRANSFORM ASCIIDOCTOR_SOURCES
- PREPEND "${CMAKE_CURRENT_SOURCE_DIR}/"
- OUTPUT_VARIABLE ABS_SRC_PATH
- )
-
-# Note: writes to source directory by default, not build directory!
-# Use "git clean -dfx" to easily completely clean a source directory.
-add_custom_target(doc-sources
- COMMAND ${ASCIIDOCTOR_PATH} ${ASCIIDOCTOR_OPTS} ${ABS_SRC_PATH}
- DEPENDS "${ASCIIDOCTOR_SOURCES}"
- )
diff --git a/doc/source-reference/IPC-notes.md b/doc/source-reference/IPC-notes.md
new file mode 100644
index 00000000..5b34a83b
--- /dev/null
+++ b/doc/source-reference/IPC-notes.md
@@ -0,0 +1,243 @@
+# IPC Notes
+
+To support the [async](https://docs.kde.org/trunk5/en/kdesrc-build/kdesrc-build/conf-options-table.html#conf-async)
+parameter, which permits network updates to be run in parallel with the build process, kdesrc-build implements
+some limited inter-process communication (IPC).
+
+In reality there are 3 separate long-term processes during an async build:
+
+ +-----------------+ +---------------+ +------------+
+ | | | | | |
+ | main / build <------ monitor <--------- update |
+ | | ^ | | ^ | |
+ +--------^--------+ | +---------------+ | +------------+
+ | | |
+ | $ipc $updaterToMonitorIPC
+ |
+ |
+ +--------v--------+
+ | |
+ user ------->| TTY |
+ | |
+ +-----------------+
+
+- 1. The main (build) process
+- 2. The update process, normally squelched
+- 3. A "monitor" process, connected to the other two
+
+## Why IPC is necessary
+
+IPC is used to carry information about the status of build updates back to the main process.
+
+Over the years this has evolved to include, using a custom app-specific protocol:
+
+- 1. Success/failure codes (per-module)
+- 2. Whether the module was even attempted to be updated at all
+- 3. Failure codes (overall)
+- 4. Log messages for a module (normally squelched during update)
+- 5. Changes to persistent options (must be forwarded to main proc to be persisted)
+- 6. "Post build" messages, which must be shown by the main thread just before exit.
+
+You could in principle do most of this by doing something like serializing
+changes into a file after each module update and then reading the results from
+the file in the main thread using file locking or similar. However it seemed
+simpler to ferry the information over IPC pipes instead.
+
+## How it works, today
+
+At this stage, the IPC data flow is mediated by [ksb::IPC](https://metacpan.org/pod/ksb%3A%3AIPC), which is an
+interface class with a couple of methods meant to be reimplemented by
+subclasses, and which implements the IPC API on top of those subclass-defined
+methods.
+
+The user code in kdesrc-build is required to create the IPC object before
+forking using ["fork" in perlfunc](https://metacpan.org/pod/perlfunc#fork). The parent then declares that it will be the
+receiver and the child declared that it will be the sender.
+
+### Monitor process
+
+Early experiments used only the two build (main) and update processes. However
+this quickly ran into issues trying to keep the main process U/I in sync.
+During a build there was no easy way to monitor the build child's output along
+with the update child's, and the update child would block if it tried to write
+too much output to the build process if the build process was itself blocked
+waiting for a build.
+
+The solution was to reinvent a message queue, poorly, for much the same reason
+you would use a message queue today in a distributed architecture. It
+simplified the problem for build and update and allowed the update process to
+send at will without blocking, and likewise the build thread did not have to
+worry about blocking by trying to read from the child unless it was safe to
+wait.
+
+The monitor simply uses a second [ksb::IPC](https://metacpan.org/pod/ksb%3A%3AIPC) object to connect to the update
+child process, and feeds messages it receives from the child to the parent, in
+the order received and exactly once.
+
+### Ordering the update and build
+
+To keep the build from proceeding before the update has completed, the IPC
+class supports methods to wait for the module to complete if it hasn't already.
+By their nature these are blocking methods, ultimately these block waiting on
+I/O from the monitor.
+
+This means that the build process will block forever if the update thread
+forgets to send the right message. The update process should build modules in
+the same order the build process will expect them, though this won't cause the
+build to block forever if it does not.
+
+### Squelching log messages
+
+The various logging methods all output the message immediately. This is
+problematic in the context of concurrent build and update processes, especially
+since most log messages do not duplicate the name of the module (since it's
+normally nearby in the U/I output).
+
+We resolve this tension by having the update process pass the IPC object into
+ksb::Debug, which will then feed the output to the IPC handle instead of
+STDOUT/STDERR. In the build process, as log messages are read in from the
+update process, they are stored and then printed out once it comes time to
+build the module.
+
+This system only works because the update and build processes are separate
+processes. The 'modern' scheme I'm building towards does not require the
+existence of a separate update process at all, but we may still retain it to
+make squelching work.
+
+### Commands that do not require IPC
+
+The log\_command() call in [ksb::Util](https://metacpan.org/pod/ksb%3A%3AUtil) also uses a fork-based construct to read
+I/O from a child (to redirect output to the log file and/or to a callback).
+
+It is safe to use this function from the update thread, as long as we are
+disciplined about using unique names for each log-file. The update process will
+set the `latest` and `error.log` symlinks as necessary, and the main process
+will find `error.log` where it expects to when making the report at the end.
+
+Note that this works only if the base log directory for the module is created
+in [ksb::BuildContext](https://metacpan.org/pod/ksb%3A%3ABuildContext) before the fork occurs!
+
+## How it will work, tomorrow
+
+Looking back, the IPC stuff I coded isn't as bad as I remember it to be. However
+there are still good reasons to work to replace it with some of the superior options
+supported by [Mojolicious](https://docs.mojolicious.org/).
+
+- Easier use of the Web and APIs
+
+ A lot of this work was kicked off based on conversations at Akademy 2018, where
+ people asked about a way to track the progress of a kdesrc-build build using
+ APIs or RPC. kdesrc-build isn't setup today to host a web server interface
+ **during** the build, and the [ksb::IPC](https://metacpan.org/pod/ksb%3A%3AIPC) stuff isn't helping on that front.
+
+ But this is what Mojolicious is built for.
+
+ However not only would it be good to have kdesrc-build be able to feed
+ information to e.g. a running Plasma applet, but it would also be good for
+ kdesrc-build to be able to make API calls to KDE infrastructure, for things
+ like bug management, creating new work branches in Gitlab, and so on.
+
+ For all these things it will be greatly helpful to have the Web-native
+ capability and event loop provided by Mojolicious.
+
+- Improved API
+
+ In addition, Mojolicious's concurrent code is just a simpler API. It doesn't
+ hurt that their "promise"-based API is the same API you'd find in JavaScript,
+ including browsers and Node.js ecosystems.
+
+ Unfortunately a lot of this is a fair bit different than what kdesrc-build has
+ been built to date. But I think I understand how to port it over time without
+ breaking everything.
+
+- Improved code correctness
+
+ Even though we ferry a lot of information from the update process to the main
+ process, there are still information types we do not that might be considered
+ bugs. For example, [ksb::OptionsBase](https://metacpan.org/pod/ksb%3A%3AOptionsBase)'s `getOption`/`setOption` methods
+ (which power the same in [ksb::Module](https://metacpan.org/pod/ksb%3A%3AModule) and [ksb::BuildContext](https://metacpan.org/pod/ksb%3A%3ABuildContext) do not make
+ any attempt to forward changes to the options dictionaries in the update
+ process back to the main process.
+
+ Mojolicious's "subprocess" feature would allow us to move the blocking portions
+ of the update command into a subprocess, while allowing the business logic to
+ be retained in the main process. This way there is only one place to call
+ `getOption`/`setOption` from, simplifying how the information flows.
+
+- Fewer bugs
+
+ Mojolicious has quite a few more users testing their code base compared to my
+ custom IPC stuff.
+
+- Finer granularity
+
+ Ultimately, Mojolicious would permit the main process to split the work of the
+ build process up to an even finer degree than "module update" or "module
+ build". This will allow the operating system a better opportunity to let
+ kdesrc-build use whatever is available between disk I/O, CPU, or network I/O.
+
+### The plan
+
+Ultimately, the plan is to introduce some porting-aid functions to [ksb::Util](https://metacpan.org/pod/ksb%3A%3AUtil)
+and use these to slowly port calls to `log_command()` to split the function into
+two parts:
+
+- 1. Generate a promise-based logging command
+- 2. Wait on the promise for the result
+
+By splitting the work into two steps we can avoid changing too much at once,
+while allowing for the slow merger of promise-based code into a chain of
+promises that can be handled at once using standard [Mojo::Promise](https://metacpan.org/pod/Mojo%3A%3APromise) methods.
+
+The significant limitation to this is that we **cannot call `promise->wait`**
+recursively!
+
+#### The recursive promise->wait issue
+
+The issue is that `promise->wait` requires that the I/O loop **not** be
+running, for much the same reason that we avoid nested event loops with
+Qt-based GUI programs. `wait` is simply a convenience method to run the event
+loop just long enough for the given promise to resolve or reject.
+
+If multiple promises are trying to `wait` at the same time in the presence of truly
+concurrent code then nothing good can happen.
+
+It might be possible to do this safely with structured concurrency (i.e. if the
+second promise being awaited were _guaranteed_ to always complete before the
+first promise then it should not be an issue). There might be a way to create a
+new [Mojo::IOLoop](https://metacpan.org/pod/Mojo%3A%3AIOLoop) to use with the inner promise so that we can safely wait on
+it.
+
+But it's better to avoid it entirely. That's why the porting methods I've written
+check to see if the I/O loop is running and, if it is, aborts the program.
+
+#### Implication of recursive waiting problems
+
+Since we can't wait recursively on promises, we generally need to port from
+blocking code to promises from leaf function calls on up.
+
+As an example if a call tree looks like:
+
+ + runAllTasks
+ \-+ handle_update
+ \-+ ksb::Module::update
+ \-+ ksb::Updater::Git::updateInternal
+ \-+ ksb::Updater::Git::updateExistingClone
+ +-+ ksb::Updater::Git::_auxFunction1
+ | \-- ksb::Updater::Git::_nestedAuxFunction1
+ \---- ksb::Updater::Git::_nestedAuxFunction2
+
+We might first port the "nested aux functions", making them create promises and
+then immediately await them so that they remain blocking.
+
+However, once we port their caller `_auxFunction1`, and make `_auxFunction1`
+create a promise and then await it to remain blocking, we **must** get rid of
+the blocking calls within the "nested aux functions", and have them deal only
+in promises.
+
+This will apply so on up the chain. At each level of the call tree that we want
+to block on a promise for each of porting, **all child calls** must be
+promise-native with no blocking at all!
+
+This can require rewriting complicated functions that have several
+"await\_result" calls to instead return a chain of promises.
diff --git a/doc/source-reference/IPC-notes.pod b/doc/source-reference/IPC-notes.pod
deleted file mode 100644
index 47c060d5..00000000
--- a/doc/source-reference/IPC-notes.pod
+++ /dev/null
@@ -1,267 +0,0 @@
-=head1 IPC Notes
-
-To support the L<async|https://docs.kde.org/trunk5/en/kdesrc-build/kdesrc-build/conf-options-table.html#conf-async>
-parameter, which permits network updates to be run in parallel with the build process, kdesrc-build implements
-some limited inter-process communication (IPC).
-
-In reality there are 3 separate long-term processes during an async build:
-
- +-----------------+ +---------------+ +------------+
- | | | | | |
- | main / build <------ monitor <--------- update |
- | | ^ | | ^ | |
- +--------^--------+ | +---------------+ | +------------+
- | | |
- | $ipc $updaterToMonitorIPC
- |
- |
- +--------v--------+
- | |
- user ------->| TTY |
- | |
- +-----------------+
-
-=over
-
-=item 1. The main (build) process
-
-=item 2. The update process, normally squelched
-
-=item 3. A "monitor" process, connected to the other two
-
-=back
-
-=head2 Why IPC is necessary
-
-IPC is used to carry information about the status of build updates back to the main process.
-
-Over the years this has evolved to include, using a custom app-specific protocol:
-
-=over
-
-=item 1. Success/failure codes (per-module)
-
-=item 2. Whether the module was even attempted to be updated at all
-
-=item 3. Failure codes (overall)
-
-=item 4. Log messages for a module (normally squelched during update)
-
-=item 5. Changes to persistent options (must be forwarded to main proc to be persisted)
-
-=item 6. "Post build" messages, which must be shown by the main thread just before exit.
-
-=back
-
-You could in principle do most of this by doing something like serializing
-changes into a file after each module update and then reading the results from
-the file in the main thread using file locking or similar. However it seemed
-simpler to ferry the information over IPC pipes instead.
-
-=head2 How it works, today
-
-At this stage, the IPC data flow is mediated by L<ksb::IPC>, which is an
-interface class with a couple of methods meant to be reimplemented by
-subclasses, and which implements the IPC API on top of those subclass-defined
-methods.
-
-The user code in kdesrc-build is required to create the IPC object before
-forking using L<perlfunc/"fork">. The parent then declares that it will be the
-receiver and the child declared that it will be the sender.
-
-=head3 Monitor process
-
-Early experiments used only the two build (main) and update processes. However
-this quickly ran into issues trying to keep the main process U/I in sync.
-During a build there was no easy way to monitor the build child's output along
-with the update child's, and the update child would block if it tried to write
-too much output to the build process if the build process was itself blocked
-waiting for a build.
-
-The solution was to reinvent a message queue, poorly, for much the same reason
-you would use a message queue today in a distributed architecture. It
-simplified the problem for build and update and allowed the update process to
-send at will without blocking, and likewise the build thread did not have to
-worry about blocking by trying to read from the child unless it was safe to
-wait.
-
-The monitor simply uses a second L<ksb::IPC> object to connect to the update
-child process, and feeds messages it receives from the child to the parent, in
-the order received and exactly once.
-
-=head3 Ordering the update and build
-
-To keep the build from proceeding before the update has completed, the IPC
-class supports methods to wait for the module to complete if it hasn't already.
-By their nature these are blocking methods, ultimately these block waiting on
-I/O from the monitor.
-
-This means that the build process will block forever if the update thread
-forgets to send the right message. The update process should build modules in
-the same order the build process will expect them, though this won't cause the
-build to block forever if it does not.
-
-=head3 Squelching log messages
-
-The various logging methods all output the message immediately. This is
-problematic in the context of concurrent build and update processes, especially
-since most log messages do not duplicate the name of the module (since it's
-normally nearby in the U/I output).
-
-We resolve this tension by having the update process pass the IPC object into
-ksb::Debug, which will then feed the output to the IPC handle instead of
-STDOUT/STDERR. In the build process, as log messages are read in from the
-update process, they are stored and then printed out once it comes time to
-build the module.
-
-This system only works because the update and build processes are separate
-processes. The 'modern' scheme I'm building towards does not require the
-existence of a separate update process at all, but we may still retain it to
-make squelching work.
-
-=head3 Commands that do not require IPC
-
-The log_command() call in L<ksb::Util> also uses a fork-based construct to read
-I/O from a child (to redirect output to the log file and/or to a callback).
-
-It is safe to use this function from the update thread, as long as we are
-disciplined about using unique names for each log-file. The update process will
-set the C<latest> and C<error.log> symlinks as necessary, and the main process
-will find C<error.log> where it expects to when making the report at the end.
-
-Note that this works only if the base log directory for the module is created
-in L<ksb::BuildContext> before the fork occurs!
-
-=head2 How it will work, tomorrow
-
-Looking back, the IPC stuff I coded isn't as bad as I remember it to be. However
-there are still good reasons to work to replace it with some of the superior options
-supported by L<Mojolicious|https://docs.mojolicious.org/>.
-
-=over
-
-=item Easier use of the Web and APIs
-
-A lot of this work was kicked off based on conversations at Akademy 2018, where
-people asked about a way to track the progress of a kdesrc-build build using
-APIs or RPC. kdesrc-build isn't setup today to host a web server interface
-B<during> the build, and the L<ksb::IPC> stuff isn't helping on that front.
-
-But this is what Mojolicious is built for.
-
-However not only would it be good to have kdesrc-build be able to feed
-information to e.g. a running Plasma applet, but it would also be good for
-kdesrc-build to be able to make API calls to KDE infrastructure, for things
-like bug management, creating new work branches in Gitlab, and so on.
-
-For all these things it will be greatly helpful to have the Web-native
-capability and event loop provided by Mojolicious.
-
-=item Improved API
-
-In addition, Mojolicious's concurrent code is just a simpler API. It doesn't
-hurt that their "promise"-based API is the same API you'd find in JavaScript,
-including browsers and Node.js ecosystems.
-
-Unfortunately a lot of this is a fair bit different than what kdesrc-build has
-been built to date. But I think I understand how to port it over time without
-breaking everything.
-
-=item Improved code correctness
-
-Even though we ferry a lot of information from the update process to the main
-process, there are still information types we do not that might be considered
-bugs. For example, L<ksb::OptionsBase>'s C<getOption>/C<setOption> methods
-(which power the same in L<ksb::Module> and L<ksb::BuildContext> do not make
-any attempt to forward changes to the options dictionaries in the update
-process back to the main process.
-
-Mojolicious's "subprocess" feature would allow us to move the blocking portions
-of the update command into a subprocess, while allowing the business logic to
-be retained in the main process. This way there is only one place to call
-C<getOption>/C<setOption> from, simplifying how the information flows.
-
-=item Fewer bugs
-
-Mojolicious has quite a few more users testing their code base compared to my
-custom IPC stuff.
-
-=item Finer granularity
-
-Ultimately, Mojolicious would permit the main process to split the work of the
-build process up to an even finer degree than "module update" or "module
-build". This will allow the operating system a better opportunity to let
-kdesrc-build use whatever is available between disk I/O, CPU, or network I/O.
-
-=back
-
-=head3 The plan
-
-Ultimately, the plan is to introduce some porting-aid functions to L<ksb::Util>
-and use these to slowly port calls to C<log_command()> to split the function into
-two parts:
-
-=over
-
-=item 1. Generate a promise-based logging command
-
-=item 2. Wait on the promise for the result
-
-=back
-
-By splitting the work into two steps we can avoid changing too much at once,
-while allowing for the slow merger of promise-based code into a chain of
-promises that can be handled at once using standard L<Mojo::Promise> methods.
-
-The significant limitation to this is that we B<cannot call C<promise-E<gt>wait>>
-recursively!
-
-=head4 The recursive promise->wait issue
-
-The issue is that C<promise-E<gt>wait> requires that the I/O loop B<not> be
-running, for much the same reason that we avoid nested event loops with
-Qt-based GUI programs. C<wait> is simply a convenience method to run the event
-loop just long enough for the given promise to resolve or reject.
-
-If multiple promises are trying to C<wait> at the same time in the presence of truly
-concurrent code then nothing good can happen.
-
-It might be possible to do this safely with structured concurrency (i.e. if the
-second promise being awaited were I<guaranteed> to always complete before the
-first promise then it should not be an issue). There might be a way to create a
-new L<Mojo::IOLoop> to use with the inner promise so that we can safely wait on
-it.
-
-But it's better to avoid it entirely. That's why the porting methods I've written
-check to see if the I/O loop is running and, if it is, aborts the program.
-
-=head4 Implication of recursive waiting problems
-
-Since we can't wait recursively on promises, we generally need to port from
-blocking code to promises from leaf function calls on up.
-
-As an example if a call tree looks like:
-
- + runAllTasks
- \-+ handle_update
- \-+ ksb::Module::update
- \-+ ksb::Updater::Git::updateInternal
- \-+ ksb::Updater::Git::updateExistingClone
- +-+ ksb::Updater::Git::_auxFunction1
- | \-- ksb::Updater::Git::_nestedAuxFunction1
- \---- ksb::Updater::Git::_nestedAuxFunction2
-
-We might first port the "nested aux functions", making them create promises and
-then immediately await them so that they remain blocking.
-
-However, once we port their caller C<_auxFunction1>, and make C<_auxFunction1>
-create a promise and then await it to remain blocking, we B<must> get rid of
-the blocking calls within the "nested aux functions", and have them deal only
-in promises.
-
-This will apply so on up the chain. At each level of the call tree that we want
-to block on a promise for each of porting, B<all child calls> must be
-promise-native with no blocking at all!
-
-This can require rewriting complicated functions that have several
-"await_result" calls to instead return a chain of promises.
diff --git a/Internals.txt b/doc/source-reference/Internals.md
similarity index 99%
rename from Internals.txt
rename to doc/source-reference/Internals.md
index 08198e6d..e11d8b18 100644
--- a/Internals.txt
+++ b/doc/source-reference/Internals.md
@@ -1,4 +1,4 @@
-Title: Module list construction
+# Module list construction
An overview of the steps performed in constructing the module list:
diff --git a/doc/source-reference/ksb/Module.adoc b/doc/source-reference/Module.md
similarity index 97%
rename from doc/source-reference/ksb/Module.adoc
rename to doc/source-reference/Module.md
index fe73d9ac..108510c6 100644
--- a/doc/source-reference/ksb/Module.adoc
+++ b/doc/source-reference/Module.md
@@ -1,6 +1,6 @@
-= ksb::Module
+# ksb::Module
-== DESCRIPTION
+## DESCRIPTION
This is ksb::Module, one of the core classes within kdesrc-build. It represents
any single "buildable" module that kdesrc-build can manage. It acts as a common
@@ -13,12 +13,12 @@ The many options available to the user are managed using setOption/getOption
kdesrc-build manages persistent metadata for each module as well, see
{set,get}PersistentOption
-== METHODS
+## METHODS
The basic description of each method is listed here for ease of reference. See
the source code itself for more detail.
-=== Perl integration
+### Perl integration
These functions are used to integrate into the Perl runtime or for use from
other Perl modules.
@@ -29,7 +29,7 @@ other Perl modules.
* ``compare``, for sorting ksb::Modules amongst each other based on name.
-=== CONFIGURATION
+### CONFIGURATION
These functions are used to configure what the ksb::Module object should do,
change settings, etc.
@@ -58,12 +58,12 @@ change settings, etc.
* ``unsetPersistentOption``, removes an existing persistent option.
-=== INTROSPECTION
+### INTROSPECTION
These functions are generally just read-only accessors of information about the
object.
-==== BASIC INFORMATION
+#### BASIC INFORMATION
* ``name``, returns the module name. Only one module with a given name can be
present during a build.
@@ -77,7 +77,7 @@ object.
* ``moduleSet``, returns the ksb::ModuleSet that was assigned earlier as the
source set. If no module set was assigned, returns a valid (but null) set.
-==== PLUGIN HANDLERS
+#### PLUGIN HANDLERS
* ``scm``, **autodetects** the appropriate scm plugin if not already done (or
manually set), and then returns the ksb::Updater plugin.
@@ -96,7 +96,7 @@ object.
Can be a Git-style SHA or something else entirely.
Can case an autodetection of the scm plugin.
-==== PATHS
+#### PATHS
Various path-handling functions. These aren't always easy to tell what they do
just from the method name, sadly.
@@ -135,7 +135,7 @@ just from the method name, sadly.
* ``installationPath``, as labeled on the tin. Prefers the 'prefix' option but
falls back to 'install-dir' if not set.
-==== USER AND PERSISTENT OPTIONS
+#### USER AND PERSISTENT OPTIONS
* ``getOption``, returns the value of the given named option. If no such option
exists, inherits the same value from the module's build context. If no such
@@ -165,7 +165,7 @@ just from the method name, sadly.
kdesrc-build run. kdesrc-build uses the location of the rc-file to determine
where to look for data from prior runs.
-==== KDE-SPECIFIC HANDLERS
+#### KDE-SPECIFIC HANDLERS
* ``fullProjectPath``, returns the logical module path in the git.kde.org
infrastructure for the module, if it's defined from a kde-projects module
@@ -176,7 +176,7 @@ just from the method name, sadly.
``moduleSet()`` function should return a ksb::ModuleSet that is-a
ksb::ModuleSet::KDEProjects.
-=== OPERATIONS
+### OPERATIONS
* ``update``, which executes the update (or pretends to do so) using the
appropriate source control system and returns a true/false value reflecting
diff --git a/doc/source-reference/README b/doc/source-reference/README
deleted file mode 100644
index ed64de9f..00000000
--- a/doc/source-reference/README
+++ /dev/null
@@ -1,16 +0,0 @@
-I'm working (again) on trying to document some of what this code actually does.
-
-I've really tried hard to get used to Perl's POD format but it's not happening.
-NaturalDocs didn't work well either.
-
-I actually switched to Sphinx but it's pretty difficult to have it hyperlink to
-(or even understand) Perl code, and the syntax is more annoying than I'd
-expected of rST.
-
-So right now I'm going for AsciiDoc, using the AsciiDoctor software (since
-AsciiDoc itself carries a 700MB install cost even for its minimal 'base'
-release, at least on Ubuntu).
-
-Until I add that into the build chain for kdesrc-build, it should be as simple
-as installing it (sudo apt-get install asciidoctor) and then running
-"asciidoctor index.adoc ksb/*.adoc" for now.
diff --git a/doc/source-reference/index.adoc b/doc/source-reference/index.md
similarity index 83%
rename from doc/source-reference/index.adoc
rename to doc/source-reference/index.md
index 4353d56c..b80ec7de 100644
--- a/doc/source-reference/index.adoc
+++ b/doc/source-reference/index.md
@@ -1,7 +1,7 @@
-= kdesrc-build documentation:
+# kdesrc-build documentation
+
Michael Pyne <mpyne at kde.org>
v18.12, 2018-11-22
-:webfonts!:
kdesrc-build is intended to build KDE-based software from its source repository, although it can build
other types of software from its native source control system(s) as well.
@@ -9,11 +9,11 @@ other types of software from its native source control system(s) as well.
This documentation is intended for developers to aid in hacking on kdesrc-build itself, or porting the same concepts
to other build systems if necessary.
-== Concepts
+## Concepts
Some basic concepts are assumed throughout for brevity.
-=== Modules
+### Modules
kdesrc-build uses the "module" as the most granular level of buildable
software. Each module has a name, unique in the list of all modules.
@@ -21,7 +21,7 @@ Each module can have a specific source control system plugin (Git,
KDE's git, etc.) and a build system plugin (qmake, CMake, KDE's
CMake, autotools, etc.)
-=== Build Phases
+### Build Phases
A module's build process progresses through build phases, which are often
optional.
@@ -40,16 +40,16 @@ phases, under the theory that the build phase is usually CPU-heavy so it makes
sense to start on subsequent network (IO-heavy) updates while the build
progresses.
-=== Build Context
+### Build Context
To group global settings and status together that exist across individual
modules, a "build context" is used, shared across the entire application.
Each module can refer to the global build context.
-=== Configuration file (rc-file)
+### Configuration file (rc-file)
-kdesrc-build uses a configuration file (usually abbreviated the `+rc-file+`) to
+kdesrc-build uses a configuration file (usually abbreviated the `rc-file`) to
store:
. The list of modules to build, and
@@ -57,17 +57,17 @@ store:
. The build or configuration options to use by default or on a per-module
basis.
-When kdesrc-build is run, it will use `+kdesrc-buildrc+` located in the current
+When kdesrc-build is run, it will use `kdesrc-buildrc` located in the current
working directory. If this file is not present, the global rc-file at
-`+~/.config/kdesrc-build/kdesrc-buildrc+`
-(`+$XDG_CONFIG_HOME/kdesrc-build/kdesrc-buildrc+`, if `+XDG_CONFIG_HOME+`
+`~/.config/kdesrc-build/kdesrc-buildrc`
+(`$XDG_CONFIG_HOME/kdesrc-build/kdesrc-buildrc`, if `XDG_CONFIG_HOME`
environment variable is set) is used instead.
-If neither of above is found, kdesrc-build will fallback to `+~/.kdesrc-buildrc+`.
+If neither of above is found, kdesrc-build will fallback to `~/.kdesrc-buildrc`.
This location is checked only for backward compatibility; it is advised to move
the configuration file to the XDG compliant path instead.
-=== Command line
+### Command line
kdesrc-build uses the command line (seen as "cmdline" in the source and commit
logs) to override the list of modules to build (nearly always still requiring
@@ -78,7 +78,7 @@ control output verbosity and so on.
In theory every option in the rc-file can be set from the cmdline, and cmdline
entries override and mask any options used by default or read from an rc-file.
-=== Module Sets
+### Module Sets
With the adoption of git, KDE exploded to having hundreds of repositories. It
would be annoying and error-prone to try to manually update the rc-file with
@@ -88,14 +88,14 @@ Because of this, kdesrc-build supports grouping modules into "module sets" of
modules that have common options and a common repository URL prefix, as if the
user had manually entered those modules one by one.
-NOTE: This is controlled by the `+git-repository-base+` option to set the URL
-prefix, the `+repository+` option to choose one of the defined bases, and the
-`+use-modules+` option to list module names.
+NOTE: This is controlled by the `git-repository-base` option to set the URL
+prefix, the `repository` option to choose one of the defined bases, and the
+`use-modules` option to list module names.
-==== KDE module sets
+#### KDE module sets
To support the KDE repositories in particular, a special module set repository
-is defined, `+kde-projects+`. Use of this repository enables some extra magic
+is defined, `kde-projects`. Use of this repository enables some extra magic
in the modules that are ultimately defined from such a module set, including
automagic dependency handling and inclusion of modules based on a virtual KDE
project structure.
@@ -103,9 +103,9 @@ project structure.
NOTE: Inclusion of modules is **separate** from dependency handling, which is
also supported!
-=== Pretend mode
+### Pretend mode
-The user can pass a `+--pretend+` cmdline flag to have kdesrc-build not
+The user can pass a `--pretend` cmdline flag to have kdesrc-build not
actually undertake the more time or resource intensive actions, so that the
user can see what kdesrc-build would do and tweak their cmdline until it looks
correct, and then remove the --pretend flag from there.
@@ -113,9 +113,9 @@ correct, and then remove the --pretend flag from there.
This significantly influences the design of the script, both in action and
output.
-=== Logs and build output
+### Logs and build output
-All build commands are logged to a file (see `+log_command+` in ksb::Util).
+All build commands are logged to a file (see `log_command` in ksb::Util).
This is both to declutter the terminal output and to enable troubleshooting
after a build failure.
@@ -133,14 +133,14 @@ of log_command)!
Some users prefer to have TTY output. For now the --debug cmdline option is
useful for that, but --debug has a significant amount of other changes as well.
-== Basic flow
+## Basic flow
For each script execution, kdesrc-build generically goes through the following
steps:
. Read the cmdline to determine global options, list of module *selectors*
(modules are defined later) and potentially alternate rc-files to use.
-. Opens the selected rc-file (chosen on cmdline or based on `+$PWD+`) and reads
+. Opens the selected rc-file (chosen on cmdline or based on `$PWD`) and reads
in the list of modules and module-sets in the rc-file along with the options
chosen for each.
. Ensures that the KDE git repository metadata is available (containing
@@ -156,7 +156,3 @@ these two steps concurrently:
.. Performs remaining module build steps in order (waiting for the update if
needed).
. When all update/build processes are done, displays the results to the user.
-
-== List of Packages
-
-* <<ksb/Module#,ksb::Module>>
diff --git a/doc/source-reference/perl-upgrade-notes.pod b/doc/source-reference/perl-upgrade-notes.pod
deleted file mode 100644
index a04fa677..00000000
--- a/doc/source-reference/perl-upgrade-notes.pod
+++ /dev/null
@@ -1,318 +0,0 @@
-=head1 Perl Upgrade Notes
-
-As Perl 5 evolves, they gain features that may be useful to adopt in
-kdesrc-build.
-
-This notes some of the important ones for consideration, for molding into
-modules/ksb.pm (which is the base package imported by all Perl-using code) or
-usage elsewhere.
-
-Currently we require 5.28 as a minimum.
-
-=head2 Release Dates
-
-This shows release dates for versions of Perl we don't yet mandate as a guide
-to when it might make sense to bump the Perl requirement for mainline
-development.
-
-=over
-
-=item *
-
-Perl 5.36 was released 28 May 2022
-
-=item *
-
-Perl 5.34 was released 20 May 2021
-
-=item *
-
-Perl 5.32 was released 20 June 2020
-
-=item *
-
-Perl 5.30 was released 19 May 2019
-
-=item *
-
-Perl 5.28 was released 22 June 2018 and is the I<currently mandated version> of Perl.
-
-=back
-
-=head2 Per-version notes
-
-=head3 For 5.12
-
-See L<perldelta for this version|https://perldoc.perl.org/perl5120delta> for more detail.
-
-=over
-
-=item *
-
-New package decl syntax "package Foo v1.24"
-
-=item *
-
-"use 5.18.0" will enable *both* `strict` and extra features for that version.
-
-=item *
-
-`each keys value` functions all work on arrays now.
-
-=item *
-
-filehandles are always in IO::File.
-
-=item *
-
-`use parent` available.
-
-=item *
-
-Consider `autodie`
-
-=item *
-
-Consider `IPC::Cmd` to replace slurp\_program\_output and friends.
-
-=back
-
-=head3 For 5.14
-
-See L<perldelta for this version|https://perldoc.perl.org/perl5140delta> for more detail.
-
-=over
-
-=item *
-
-Consider `unicode_strings` pragmas?
-
-=item *
-
-Non-destructive subs: my $old = $new =~ s/foo/bar/r; (/r flag important!)
-
-=item *
-
-Array / hash functions operate directly on references. But this was removed in Perl 5.24
-in favor of
-L<postfix dereferences|https://www.effectiveperlprogramming.com/2014/09/use-postfix-dereferencing/>.
-so don't bother with them.
-
-=item *
-
-package syntax supports BLOCKs now (package Foo v1.2 { ... } does what it looks like)
-
-=item *
-
-`given` now has a return value, making `when` statements useful.
-
-=back
-
-=head3 For 5.16
-
-See L<perldelta for this version|https://perldoc.perl.org/perl5160delta> for more detail.
-
-=over
-
-=item *
-
-__SUB__ token references current subroutine (useful for logging)
-
-=back
-
-=head3 For 5.18
-
-See L<perldelta for this version|https://perldoc.perl.org/perl5180delta> for more detail.
-
-=over
-
-=item *
-
-Lexical subs (e.g. my sub foobar { my @foo = @\_ }, etc.).
-
-=item *
-
-Can use 'computed gotos' for next, last, redo (i.e. switch at runtime)
-
-=back
-
-=head3 For 5.20
-
-See L<perldelta for this version|https://perldoc.perl.org/perl5200delta> for more detail.
-
-=over
-
-=item *
-
-Function signatures (experimental): sub foo($a, $b) { # use $a, $b }
-
-=item *
-
-%hash{},%array[] syntax that returns a hash (perldata Key/Value Hash Slices)
-
-=item *
-
-Postfix Deref (experimental): $aref->@*, $href->%{key}, etc.
-
-=item *
-
-use locale supports UTF-8 locales.
-
-=back
-
-=head3 For 5.22
-
-See L<perldelta for this version|https://perldoc.perl.org/perl5220delta> for more detail.
-
-=over
-
-=item *
-
-Something about numeric/string bitwise operators.
-
-=item *
-
-Safer <<>> operator
-
-=item *
-
-re strict flag (experimental)
-
-=item *
-
-re non-capture flag
-
-=item *
-
-'constant functions' (experimental, perlsub Constant Functions)
-
-=back
-
-=head3 For 5.24
-
-See L<perldelta for this version|https://perldoc.perl.org/perl5240delta> for more detail.
-
-=over
-
-=item *
-
-Postfix Deref no longer experimental and always enabled.
-
-=back
-
-=head3 For 5.26
-
-See L<perldelta for this version|https://perldoc.perl.org/perl5260delta> for more detail.
-
-=over
-
-=item *
-
-Experiment to create references to scalar vars ('declared_refs')
-
-=item *
-
-Indented here docs (<<~FOO)
-
-=item *
-
-Lexical subs are no longer experimental
-
-=back
-
-=head3 For 5.28
-
-See L<perldelta for this version|https://perldoc.perl.org/perl5280delta> for more detail.
-
-=over
-
-=item *
-
-Bitwise operators enabled by default.
-
-=item *
-
-Can delete key/value hash slices
-
-=back
-
-=head3 For 5.30
-
-See L<perldelta for this version|https://perldoc.perl.org/perl5300delta> for more detail.
-
-=over
-
-=item *
-
-Nothing big
-
-=back
-
-=head3 For 5.32
-
-See L<perldelta for this version|https://perldoc.perl.org/perl5320delta> for more detail.
-
-=over
-
-=item *
-
-Can turn off indirect object syntax (no feature 'indirect')
-
-=item *
-
-Experiment to add 'isa' core operator.
-
-=item *
-
-Chained comparison
-
-=back
-
-=head3 For 5.34
-
-See L<perldelta for this version|https://perldoc.perl.org/perl5340delta> for more detail.
-
-=over
-
-=item *
-
-try/catch syntax
-
-=back
-
-=head3 For 5.36
-
-See L<perldelta for this version|https://perldoc.perl.org/perl5360delta> for more detail.
-
-=over
-
-=item *
-
-C<isa> and various other features we don't use are now enabled by default
-
-=item *
-
-You can iterate multiple variables at a time through lists and hashes using the
-experimental C<for_list> feature.
-
- for my ($key, $value) (%hash) { ... }
-
-Seems handy!
-
-=item *
-
-Some new builtin functions under the C<builtin> namespace. Of note are C<trim>,
-C<indexed>, functions relating to reference weakening (something we do zero of
-but apparently can help save memory) and C<ceil> / C<floor>.
-
-=item *
-
-C<defer> blocks have been added, saving one from having to write an entire Perl
-package just to run a C<DESTROY> block on a blessed reference to get RAII-style
-semantics or scope guards.
-
-=item *
-
-The experimental try/catch stuff can have a C<finally> block as well now.
-
-=back
diff --git a/doc/source-reference/serve-docs.pl b/doc/source-reference/serve-docs.pl
deleted file mode 100755
index 6aa3cf28..00000000
--- a/doc/source-reference/serve-docs.pl
+++ /dev/null
@@ -1,181 +0,0 @@
-#!/usr/bin/env perl
-
-use v5.28;
-
-eval {
- use Mojolicious::Lite;
-};
-
-if ($@) {
- say <<EOF
-Mojolicious::Lite and Mojolicious::Plugin::PODViewer must be installed (e.g.
-using CPAN-Minus) to use this script.
-EOF
-}
-
-# Add this directory and the kdesrc-build Perl modules so that they will be
-# found by the Pod::Simple search algorithm
-push @INC, '.', '../../modules';
-
-plugin 'PODViewer', {
- default_module => 'ksb',
- layout => 'default',
- route => app->routes->any('/'),
-};
-
-#push @{app->static->paths}, './static';
-
-say "Once the daemon has started, try opening links like:";
-say "\thttp://localhost:3000/perl-upgrade-notes or";
-say "\thttp://localhost:3000/ksb";
-
-push @ARGV, 'daemon' unless @ARGV; # Default to daemon
-app->start;
-
-__DATA__
-@@ layouts/default.html.ep
-<!DOCTYPE html>
-<html>
- <head>
- <meta name="viewport" content="width=device-width, initial-scale=1">
- <link rel="stylesheet" href="/water-dark.css">
- <title><%= title %></title>
- <section class="section">
- <main class="container">
- %= content
- </main>
- </section>
-</html>
-
-@@ water-dark.css
-/* From https://github.com/kognise/water.css release 2.1.1 (MIT license), stripped further */
-body {
- font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
- line-height: 1.4;
- max-width: 800px;
- margin: 20px auto;
- padding: 0 10px;
- color: #dbdbdb;
- background: #202b38;
- text-rendering: optimizeLegibility;
-}
-button, input, textarea {
- transition: background-color 0.1s linear, border-color 0.1s linear, color 0.1s linear, box-shadow 0.1s linear, transform 0.1s ease;
-}
-h1 {
- font-size: 2.2em;
- margin-top: 0;
-}
-h1, h2, h3, h4, h5, h6 {
- margin-bottom: 12px;
-}
-h1, h2, h3, h4, h5, h6, strong {
- color: #ffffff;
-}
-h1, h2, h3, h4, h5, h6, b, strong, th {
- font-weight: 600;
-}
-blockquote {
- border-left: 4px solid #0096bfab;
- margin: 1.5em 0em;
- padding: 0.5em 1em;
- font-style: italic;
-}
-blockquote > footer {
- margin-top: 10px;
- font-style: normal;
-}
-blockquote cite {
- font-style: normal;
-}
-address {
- font-style: normal;
-}
-button, input[type='submit'], input[type='button'], input[type='checkbox'] {
- cursor: pointer;
-}
-input:not([type='checkbox']):not([type='radio']), select {
- display: block;
-}
-input, select, button, textarea {
- color: #ffffff;
- background-color: #161f27;
- font-family: inherit;
- font-size: inherit;
- margin-right: 6px;
- margin-bottom: 6px;
- padding: 10px;
- border: none;
- border-radius: 6px;
- outline: none;
-}
-input:not([type='checkbox']):not([type='radio']), select, button, textarea {
- -webkit-appearance: none;
-}
-textarea {
- margin-right: 0;
- width: 100%;
- box-sizing: border-box;
- resize: vertical;
-}
-button, input[type='submit'], input[type='button'] {
- padding-right: 30px;
- padding-left: 30px;
-}
-button:hover, input[type='submit']:hover, input[type='button']:hover {
- background: #324759;
-}
-input:focus, select:focus, button:focus, textarea:focus {
- box-shadow: 0 0 0 2px #0096bfab;
-}
-input[type='checkbox']:active, input[type='radio']:active, input[type='submit']:active, input[type='button']:active, button:active {
- transform: translateY(2px);
-}
-input:disabled, select:disabled, button:disabled, textarea:disabled {
- cursor: not-allowed;
- opacity: .5;
-}
-::placeholder {
- color: #a9a9a9;
-}
-a {
- text-decoration: none;
- color: #41adff;
-}
-a:hover {
- text-decoration: underline;
-}
-code, kbd {
- background: #161f27;
- color: #ffbe85;
- padding: 5px;
- border-radius: 6px;
-}
-pre > code {
- padding: 10px;
- display: block;
- overflow-x: auto;
-}
-img {
- max-width: 100%;
-}
-hr {
- border: none;
- border-top: 1px solid #dbdbdb;
-}
-table {
- border-collapse: collapse;
- margin-bottom: 10px;
- width: 100%;
-}
-td, th {
- padding: 6px;
- text-align: left;
-}
-th {
- border-bottom: 1px solid #dbdbdb;
-}
-tbody tr:nth-child(even) {
- background-color: #161f27;
-}
-/*# sourceMappingURL=dark.css.map */
diff --git a/modules/ksb.pm b/modules/ksb.pm
index 0ad9c73e..b0abffaa 100644
--- a/modules/ksb.pm
+++ b/modules/ksb.pm
@@ -50,23 +50,6 @@ This package applies common Perl standards to all kdesrc-build modules, includin
enabling C<use strict>, C<use warnings>, requiring Perl 5.26 as a minimum version,
and enabling L<subroutine signatures|perlsub>.
-=head2 DEVELOPER GUIDE
-
-=over
-
-=item *
-
-Information on Perl improvements that may be worth targeting can be found in
-the L<perl-upgrade-notes> guide.
-
-=item *
-
-Information on how kdesrc-build supports inter-process communication to support
-concurrent build and updates can be found in L<IPC-notes>. Including how
-it's worked for years and what we're working to port to.
-
-=back
-
=head2 RELATED MODULES
Some or all of the following may be helpful as well:
More information about the kde-doc-english
mailing list