From d3f05b12b2b81fe79df4da70e139ebbc489f6ffe Mon Sep 17 00:00:00 2001 From: Jan Lindemann Date: Mon, 1 Jul 2019 14:22:24 +0000 Subject: [PATCH] README.md: Ongoing beautification Signed-off-by: Jan Lindemann --- README.md | 77 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 39 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index ef842dc5..de0ec489 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,8 @@ makefile snippets from your own projects' makefiles, like so: include $(JWBDIR)/make/cpp.mk ``` -where `JWBDIR` needs to point to jw-build's installation directory. In this -example the snippet `cpp.mk` would by default take all C++ files it finds in +where `JWBDIR` needs to point to JW-Build's installation directory. In this +example, the snippet `cpp.mk` would by default take all C++ files it finds in the directory where its included, compile them and and add them to a shared package library. `js.mk` would by default minify all JavaSript it finds, `java.mk` jar up .java files into classes and jar-files, and so on. JW-Build @@ -24,14 +24,15 @@ locations with standardish defaults. JW-Build is small. It's small enough to be self-documenting. Well, okay, somewhat self-documenting. You have to know GNU Makefile syntax to understand -what it does. You can install it with your distribution's package manager, or -you can keep it within your code versioning system, alongside your own code. -It's also designed to be the lightest possible touch on any given source code -package, in terms of code you need to add to a package you want to build with -it, and also in terms of needed prerequisite software packages. This way, it's -easily introduced - and it's also easy to get rid of, should you choose to do -so at some point in time. You will then have all your settings and compiler -flags in well-defined places already. +what it does, and dig into its code, ideally with a working example. You can +install it with your distribution's package manager, or you can keep it within +your code versioning system, alongside your own code. It's also designed to be +the lightest possible touch on any given source code package, in terms of code +you need to add to a package you want to build with it, and also in terms of +needed prerequisite software packages. This way, it's easily introduced - and +it's also easy to get rid of, should you choose to do so at some point in time. +You will then have all your settings like file system path definitions and +compiler flags in well-defined places already. JW-Build runs a recursive make, so, with a few exceptions such as submodules, you will need a makefile in every directory with source code. Most, if not all @@ -41,33 +42,33 @@ involving multiple packages - as centrally or as locally as you want. You can override any of JW-Build's default variables - for many packages, for an entire package, or for any subdirectory of a given package, at your option. You can write your own snippets and reuse them in multiple places. You can keep -overrides in your versioning system or add them to a `local.mk` which only your -machine knows about. Or you can use environment variables, of course. JW-Build -avoids makefile code generation as seen with CMake or GNU Autotools. This keeps -the code small and readable for easy debugging. Okay, for relatively easy -debugging. To achieve this, JW-Build has to detect a couple of things in every -directory it enters, but it uses various caching mechanisms to keep builds -still reasonably fast. +overrides in your versioning system or add them to `local.mk`-files as needed, +which only your machine knows about. Or you can use environment variables, of +course. JW-Build avoids makefile code generation as seen with CMake or GNU +Autotools. This keeps the code small and readable for easy debugging. Okay, for +relatively easy debugging. To achieve this, JW-Build has to detect a couple of +things in every directory it enters, but it uses various caching mechanisms to +keep builds still reasonably fast. JW-Build has makefile snippets for building libraries and executables, snippets that output code compiled from C/C++, Python, Java, JavaScript and LaTeX, and it's easily extendible to support any given programming language or task. It's in use at janware for managing sub-builds of Maven, Ant, CMake and others, and -for packaging the results. It provides targets to produce Debian, RPM and IPK -packages, install them locally or remotely, or feed them into a DevOps -pipeline, taking note of released versions within GIT, SVN or CVS. It detects -if a package needs to be re-released because its source code changed. Or because -a package it depends on has changed incompatibly. JW-Build has built-in -support for collaboration over a set of remote Git repositories. It supports a -simple configuration file per package for specifying package metadata, e.g. its -dependencies, license, description, pre- and postinstall scriptlets, and so on. -It has a SAT-solver built in, for building multiple packages in the right -order, including packages that are not organized with jw-build, based on that -metadata. With the same metadata, it can also automatically generate BitBake -recipes and run Yocto-builds incorporating your software. It generates runtime, -development and source code package variants. It supports cross compilation -with MinGW and the GNU toolchain. It's tested on Debian, Ubuntu, OpenSUSE, -Fedora / CentOS / RHEL, and many Unices. +for packaging the results. It provides targets to flash binaries onto MCUs, +produce Debian, RPM and IPK packages, install them locally or remotely, or feed +them into a DevOps pipeline, taking note of released versions within GIT, SVN +or CVS. It detects if a package needs to be re-released because its source code +changed. Or because a package it depends on has changed incompatibly. JW-Build +has built-in support for collaboration over well-defined sets of remote Git +repositories. It supports a simple configuration file per package for +specifying package metadata, e.g. its dependencies, license, description, pre- +and postinstall scriptlets, and so on. It has a SAT-solver built in, for +building multiple packages in the right order, including packages that are not +organized with JW-Build, based on that metadata. With the same metadata, it can +also automatically generate BitBake recipes and run Yocto-builds incorporating +your software. It generates runtime, development and source code package +variants. It supports cross compilation with MinGW and the GNU toolchain. It's +tested on Debian, Ubuntu, OpenSUSE, Fedora / CentOS / RHEL, and many Unices. JW-Build is designed to be friendly to both developers and integrators. Developers can cd into any given directory, edit the source code, run `make`, @@ -82,10 +83,10 @@ TARGET_HOST=myserver.acme.com make pkg-remote-install And of course, it can build, package and release itself. Without being installed, which is a Good Thing (TM). -## Documentation +## Usage See https://janware.com/wiki/pub/sw/build/ for documentation on how to get -and use JW-Build within a janware build tree. +and use JW-Build within the janware build tree. If you want to use it standalone, OTOH, do the following to get a minimal working example: @@ -101,9 +102,9 @@ containing two files: ``` `TOPDIR` points to, you guessed it, the toplevel directory of your package. - You will have defined it yourself, see the next point. Note that all + You will have defined it yourself, see the next point. Note that all directory paths can be relative, which is nice if you want to organize - trees. + multiple packages in a fixed tree layout. 2. `project.conf`, containing @@ -126,10 +127,10 @@ Done. Well, in principle. Other notable snippets are `topdir.mk` for the toplevel directory, `dirs.mk` for other directories with subdirectories, `lib.mk` for `$(TOPDIR)/lib`, `include.mk` for `$(TOPDIR)/include`, and `make.mk` for `$(TOPDIR)/make`. You should add them in the same manner. Once -you add those makefiles, running `make` will do - something. Try and see what +you add those makefiles, running `make` will do - something. Try and see what happens. Every snippet supports at least the targets `all`, `install`, `clean` and `distclean`. `make echo-makefiles` shows you all included snippets, -`cat-makefiles` concatenates them. Hitting TAB should show you all targets +`make cat-makefiles` concatenates them. Hitting TAB should show you all targets supported in a particular directory. Good luck! [logo]: https://janware.com/janware/images/logo-janware/logo-janware-200.png