commit 7f586ace5008bbc8e15c2e0cec8d4ab572e1a3c6
parent d88275be2df4c04d1368ab1dc585d67d1778f687
Author: Erik Letson <hmagellan@hmagellan.com>
Date: Sat, 15 Aug 2020 02:50:42 -0500
added README
Diffstat:
| A | README | | | 62 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 62 insertions(+), 0 deletions(-)
diff --git a/README b/README
@@ -0,0 +1,62 @@
+suckless-gf-st - Gentoo-Friendly Patches for Suckless's st
+
+== What Is This? ==
+
+ This repository contains a host of patches that can be applied to st, the simple terminal implementation from suckless.org. These
+patches have been modified to work with Gentoo's st package, and are specifically compatible with the 'savedconfig' USE flag. Each
+patch in this repository has its own directory. Each of these directories contains the actual patch file itself (ending in '.patch',
+for Portage compatibility reasons), and a file called USAGE that informs the user on any manual changes that should or might be
+applied in order to use the patch. Be sure to read USAGE carefully before applying the patch, and follow the instructions therein!
+
+ This project exists because of a problem with the default way that Suckless programs work in a Gentoo environment. Gentoo's
+package manager, Portage, offers a built-in utility for patching programs, and this utility works nicely with the patches for st
+that can be found on suckless.org. Additionally, since Portage is a source-based package manager, it also offers a utility for
+editing config.h files in Suckless programs by using the 'savedconfig' USE flag. This USE flag, when enabled, will create a directory
+in /etc/portage/savedconfig that contains a header file (this file is located in /etc/portage/savedconfig/x11-terms/ in st's case).
+This header file can be edited just like the one that you would edit if you were working with a git repository or other copy of the
+st code directly. Edits made to this file are applied as a diff to config.def.h at emerge time, thus providing a very simple and
+convenient way of incorporating Suckless's recommended modification methodology in a Portage-friendly fashion. There is a problem
+with this, however; because of the way that Portage patches programs as part of ebuilds, most of the time any patches that make
+changes to config.def.h themselves will be totally incompatible with a custom savedconfig header file, and emerge will fail if you
+try to apply such a patch while 'savedconfig' is enabled. The solution to this dilemma is to modify the patches in such a way as to
+make them never make any changes to config.def.h, and thus make them compatible with 'savedconfig' and friendly to Gentoo. Any
+changes that the patch originally tried to make to config.def.h could either be applied manually to the savedconfig header file by
+the user, or potentially included in another file as part of the patching process, depending on what the changes do.
+
+ A side-goal of this repository is to make each target patch (see below) support the current stable version of x11-terms/st as
+offered by Gentoo tree (currently st version 0.8.4). Many of the patches suckless-gf-st targets are not themselves considered to be
+compatible with this modern version of st, but the project intends to fix any compatibilty issues that the target patches have with
+the unmodified current st codebase and thus make them work. This could potentially result in substantial changes coming to individual
+patches, or perhaps the total rewrite of patches altogether. Compatibility changes will be noted in individual patches' USAGE files.
+
+ These patches are ALL compatible with Portage and savedconfig. Effort has also been taken to ensure the patches are themselves
+cross-compatible; that is, that they do not conflict with each other. Despite this effort, lack of conflict between patches is not
+guaranteed at this time. If any specific patches are known to be incompatible with each other, the conflict will be noted inside the
+patches' USAGE files. Normally, this should serve to document most incompatiblities, but in the case of the user applying a great many
+patches all at once, it is possible that novel conflicts may occur. Be aware of this should you try to emerge with a huge number of
+patches!
+
+== Target Patches ==
+
+ suckless-gf-st targets the patches located at the following locations:
+
+ (1). https://st.suckless.org/patches/
+
+ CURRENT PROGRESS: 1/51 patches supported
+ 0/51 patches unsupported
+
+ USUPPORTED PATCHES:
+ None so far :-)
+
+ NOTE THAT UNSUPPORTED PATCHES SHOULD BE SUPPORTED IN THE FUTURE!!!
+
+== License ==
+
+ suckless-gf-st is released under the MIT/X Consortium License, the same license that st itself is under:
+ (https://git.suckless.org/st/file/LICENSE.html)
+
+ See the LICENSE file for details.
+
+== Maintainer ==
+
+ suckless-gf-st is maintained by Erik Letson <hmagellan@hmagellan.com>. Please direct any questions or patches to that email.
