--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/uwproj.md Fri Nov 29 21:43:32 2024 +0100
@@ -0,0 +1,115 @@
+## Overview
+
+UWproj is a configure script generator for make-based build systems. The generated scripts resemble GNU Autoconf configure scripts in appearance and behavior, making them familiar to users who just want to build the software. However the underlying system is significantly less complex. The output is just a single *config.mk* file, that can be included by makefiles.
+
+Currently, UWproj does not contain any makefile generator, however this might change in the future.
+
+## Project Status
+
+UWproj is not released yet, and I do not encourage anyone to use it at this stage. However, it is used in my personal projects, so anyone inspecting those build systems might encounter UWproj and wonder what it is. This page exists primarily to inform such individuals about my somewhat unconventional build system.
+
+That doesn't mean it is unusable, if anyone likes it and wants to use it, I am happy to support their efforts.
+
+## Why Not Autoconf
+
+GNU autotools are widely used and anyone knows how to build software with `./configure; make; make install` and how to setup the install prefix and other settings. That's why I personally prefer having a configure script and not any other build system like cmake. However autoconf is really old and some conecpts are probably outdated. It is overly complex, slow, many checks are unnecessary these days and debugging the generated script is not fun.
+
+UWproj approaches things differently and introduces some improvements:
+
+ - In general, source code repositories already include a pre-generated configure script. This allows users to check out the code and build it without additional steps like running autoreconf (or uwproj)
+ - The script contains far fewer tests, mostly checks for the compiler and dependencies
+ - If dependencies are missing, the uwproj configure script lists all missing dependencies, no need to run the script 10 times for 10 different error messages
+
+## Example
+
+UWproj uses a `project.xml` file to generate a configure script. Here is a simple example:
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <project xmlns="http://unixwork.de/uwproj">
+ <!-- global dependency for all targets -->
+ <dependency>
+ <!-- check if a C Compiler is available, this will add the CC variable to the config.mk file -->
+ <lang>c</lang>
+ </dependency>
+
+ <!-- libxml2 pkg-config check -->
+ <dependency name="libxml2">
+ <!-- this will run pkg-config --cflags and pkg-config --libs for the specified package -->
+ <pkgconfig>libxml-2.0</pkgconfig>
+ </dependency>
+ <!-- libxml2 xml2-config check -->
+ <dependency name="libxml2">
+ <!-- any command can be used to add CFLAGS -->
+ <cflags exec="true">xml2-config --cflags</cflags>
+ <ldflags exec="true">xml2-config --libs</ldflags>
+ </dependency>
+
+ <!-- openssl on bsd-like systems, but not on macos -->
+ <dependency name="openssl" platform="bsd" not="macos">
+ <!-- static flags without any command -->
+ <ldflags>-lssl -lcrypto</ldflags>
+ </dependency>
+ <dependency name="openssl">
+ <pkgconfig>openssl</pkgconfig>
+ </dependency>
+ <dependency name="openssl">
+ <pkgconfig>openssl</pkgconfig>
+ </dependency>
+
+ <!--
+ targets have their own CFLAGS/LDFLAGS with the target name as prefix
+ MYTARGET_CFLAGS
+ MYTARGET_LDFLAGS
+ -->
+ <target name="mytarget">
+ <dependencies>libxml2,openssl</dependencies>
+ </target>
+
+ <target name="other">
+ <dependencies>libxml2</dependencies>
+ </target>
+ </project>
+
+The configure script generated by uwproj will then check the dependencies and generates a *config.mk* file, that contains *CFLAGS/LDFLAGS* for the targets.
+
+There are two types of dependencies: general dependencies without a name, and named dependencies. Named dependencies can be specified multiple times for different variations. For example, there is a check if *libxml-2.0* is available via pkg-config, but if this check fails, the alternative *xml2-config* is used.
+
+## Howto
+
+Clone the repository:
+
+ $ hg clone https://code.unixwork.de/hg/uwproj
+
+Build (requires jdk and maven)
+
+ $ cd uwproj
+ $ mvn package
+
+Install (as root):
+
+ $ cd dist
+ $ ./install.sh
+
+Create a new uwproj based project somewhere:
+
+ $ uwproj --init
+
+The init command creates a *make* directory, that contains all required files, including an empty *project.xml* file. Run *uwproj* to generate a configure script:
+
+ $ uwproj
+ In: make/project.xml
+ Tpl: make/configure.vm
+ Out: configure
+
+# Documentation
+
+Doesn't exist yet, however there is a *.xsd* file. For more examples, check out these projects: [dav][e0], [idav][e1], [ucx][e2].
+
+[e0]: https://code.unixwork.de/hg/dav
+[e1]: https://code.unixwork.de/hg/idav
+[e2]: https://uap-core.de/hg/ucx
+
+# Why Java? It sucks.
+
+I know. I used Java for the first prototype, which is now the final product. Rookie mistake.
+
