README for kos-ports
Copyright (C) 2015, 2023 Lawrence Sebald
--------------------------------------------------------------------------------

Introduction
------------
Welcome to the newest iteration of the kos-ports system. As I'm sure you already
know, kos-ports is a repository of various useful libraries that have been
ported to KOS over the years. These libraries provide various tools such as
image reading support, archive file reading and writing, and even a OpenGL-like
environment. Each port is meant to be as self-contained as possible (which does
not mean it can't have dependent ports, of course) and should build on the
current version of KallistiOS with minimal fuss.

For those of you familiar with FreeBSD at all, this works a lot like their
ports collection (indeed, that's what I modeled it after). To build a port, it
should be as easy as going into that port's directory in a terminal and typing
    make install clean
into the terminal. If all goes well, the port will be built and installed inside
the ports tree, ready to be used.

This new version of the kos-ports tree sprung into being in May of 2015 and will
be included with the next version of KOS to be released after that point.


Dependencies
------------
kos-ports has very few external dependencies beyond a normally functioning KOS
toolchain. Here's the list:

1. Some way of downloading files from the terminal. The ports collection uses
   curl by default, but there's a configuration option to use whatever tool you
   might happen to have (and an example of using wget).
2. Git and SVN are required for some of the ports in the ports collection.
3. In order to validate downloaded source packages, Python is needed. Python
   2.7.x and 3.7.x and newer have been tested and found working. If you don't
   have Python, please edit the config.mk file to disable source package
   validation (or, better yet, install Python).
4. GNU make and Bash. Other make tools and shells have not been tested and
   may not work properly.


Differences from the old ports tree
-----------------------------------
Unlike the old ports tree, this new ports tree is meant to not keep all of the
source code of each port in our own private copies. Basically, it's designed to
make sure we try to at least keep mostly up-to-date with the upstream versions
of libraries. In the past, we'd pretty much settle on one version of a library
for a very long time, never updating it until we had to. ;-)

In addition, this new version of the ports tree can enforce things like
dependencies between libraries. That is to say, for a library like libpng that
requires another library (zlib), the new ports tree will make sure you've
satisfied the dependencies at build time to avoid any surprises later.


Using the ports tree
--------------------
There are a few targets that can be built in each port's directory that are
available. Here's a brief rundown of each make target that you might be
interested in:

- install: Perform all steps to download, patch, build, and install the port in
           question. Generally this is the one target you want (along with the
           next one).
- clean: Clean up any dist files and intermediate build results.
- uninstall: Uninstall the port. This does not make sure dependencies are still
             fulfilled, so keep that in mind.
- portinfo: Print to the terminal a description and various metadata about the
            port in question.

Lesser used targets (mainly for internal use):
- clean-dist: Clean up any dist files. Does not clean build files.
- clean-build: Cleans up build files, leaving dist files in place.
- fetch: Download dist files from upstream.
- build-stamp: Build the port, but do not install it.
- version-check: Check the version of the port that is currently installed.
- depends-check: Check if all dependencies of the port are installed.
- unpack: Unpack any fetched packages for the port.
- validate-dist: Check downloaded distfiles for validity (if enabled).


Porting a new library
---------------------
Porting a new library is meant to be a relatively simple task. I recommend
looking at an existing port to get the idea (libpng is a good one to look at).
Describing the whole process would probably take a lot of work, so I'll leave it
as an exercise for the reader here. ;-)