From 70cdcc011e9b9efb586d1b94770f6671573c93ad Mon Sep 17 00:00:00 2001
From: Philippe PITTOLI
Date: Mon, 27 Apr 2020 03:56:40 +0200
Subject: [PATCH] build.zsh improved + sass (blue).
---
content/baguette/index.md | 118 ++++++++++++++++++++++++++++++++------
sass/custom.scss | 5 ++
2 files changed, 105 insertions(+), 18 deletions(-)
diff --git a/content/baguette/index.md b/content/baguette/index.md
index 6f50107..b68ae2f 100644
--- a/content/baguette/index.md
+++ b/content/baguette/index.md
@@ -829,31 +829,68 @@ The most useful thing to do right now is to provide new services.
### [Build.zsh][build.zsh]: makefile creation. *for mere mortals*
+A `Makefile` is very useful to share your project, whatever your project is, no matter if it is an application, a library, the language used, etc.
+
Build.zsh creates a makefile from a simple declarative configuration file.
A `Makefile` should:
-- **build the application**
- This means a few things:
- - compile and link your applications
- - handle dependencies between files to build
- - rebuild only updated parts of the application, for incremental builds
- - allow users to rebuid any part of your project independently
+- **compile and link the application**
+- **handle dependencies** and **rebuild only updated parts of the application** *for incremental builds*
+- **allow users to rebuid any part of your project independently**
- **install the application**
- The default installation root directory is `/usr/local` but you should be able to change that easily (and with an environment variable).
+ The default installation root directory is `/usr/local` but you should be able to change that easily (with an environment variable or through configuration).
- **create a tarball of the project**
- Very useful to share your project, whatever your project is.
- No matter if it is an application, a library, the language used, etc.
-- **have a `make help`**
+ This tarball includes your application, its man-pages, the Makefile to build it, etc.
+- **have a `make help`** *everybody needs help*
+- *(BONUS)* have colors. I like colors.
-Here is a quick example of what `build.zsh` can do:
+**How-to generate a Makefile using `Build.zsh`**
```zsh
-package=my-application
-version=2.18.3
-
-# target = all the
-target=()
+$ ls project.zsh # we need to create this file, we'll cover that in a moment
+project.zsh
+```
+```zsh
+$ build.zsh -c # -c is for colors. I like colors. Really.
+```
+```zsh
+$ ls Makefile # tadaaaaa you made a Makefile
+Makefile
```
-Here is a real-life example:
+You can invoke your newly created Makefile with `make help` to know what can it do for you.
+For example, it can create a tarball with `make dist`.
+
+**How-to make a `project.zsh` for `build.zsh`**
+```zsh
+# File `project.zsh`
+
+package=my-application # Name of your package.
+version=2.18.3 # Version of the package (will follow the application version, probably).
+
+# targets = all the applications we want to compile in the project
+targets=(my-application)
+
+# Then, we tell the language of these applications.
+# Here, my-application is coded in Crystal.
+# build.zsh comes with a number of back-ends: https://git.baguette.netlib.re/Baguette/build.zsh/src/branch/master/build
+type[my-application]=crystal
+
+# sources are the sources of the application
+sources[my-application]=src/main.cr
+
+# The application depends on a number of files.
+# Each modification of one of these files = we have to re-compile.
+depends[my-application]="$(find src -type f | grep -v main.cr)"
+
+# Finally, we want to know what are the files we want in the tarball (made though `make dist`).
+# Here, we want to provide in our tarball:
+# the application binary,
+# man-pages in man/ directory,
+# this project.zsh and the generated Makefile
+dist=(my-application man/*[1-9] project.zsh Makefile)
+```
+
+**`Build.zsh`: a real-life example**
+
```zsh
package=build_zsh # Name of the package.
version=0.2.1 # Version of the package.
@@ -878,7 +915,52 @@ done
dist=(build.zsh.in build/*.zsh project.zsh Makefile)
```
-Don't like Makefiles? We may even add some other back-ends.
+**Another real-life example** *I like examples*
+This time, we want to build a Makefile for a C library.
+
+```zsh
+package=libipc # Package name.
+version=0.5.1 # Package version.
+
+# Our targets are the library and its documentation.
+targets=(libipc man/libipc.7)
+
+# The libipc target is a library ("for the C language" is implied).
+# The `library` type automatically adds tho targets:
+# `target`.so of type `sharedlib`
+# `target`.a of type `staticlib`
+type[libipc]=library
+# Sources are added by default to the tarball.
+sources[libipc]="$(ls src/*.c)"
+
+depends[libipc]=$(ls src/*.h)
+
+# We need to add extra compilation flags.
+variables+=(CFLAGS "-Wall -Wextra -g")
+
+# Let's add some CFLAGS, with another syntax.
+cflags[libipc]="-std=c11"
+
+# The man/libipc.7 target is a manual generated with `scdoc`.
+# `scdocman` is one of the many back-ends of build.zsh: https://git.baguette.netlib.re/Baguette/build.zsh
+type[man/libipc.7]=scdocman
+
+# Finally, we tell what we want in the tarball, generated with `make dist`.
+dist=(libipc.so libipc.a) # The library in both shared and static versions.
+dist+=(man/*.scd man/*.[1-9]) # Manual pages (and sources).
+dist+=(Makefile project.zsh) # The generated Makefile and this project.zsh.
+```
+
+This example shows how to work with C libraries, but it wouldn't have changed much for an application: only the `type` of the target would change.
+This `project.zsh` comes from the [LibIPC repository][libipc] (a library we'll see soon).
+
+**What about now?**
+Now you do not have any good reason avoiding Makefiles for your projects!
+
+***But, I don't like Makefiles!***
+You like the functionalities we presented here, but you want an alternative to the Makefile?
+We may add some other back-ends.
+Stay tuned!
[Back to top](#top)
diff --git a/sass/custom.scss b/sass/custom.scss
index 86057b0..2e14902 100644
--- a/sass/custom.scss
+++ b/sass/custom.scss
@@ -18,6 +18,11 @@ red {
font-weight: bold;
}
+blue {
+ color: blue;
+ font-weight: bold;
+}
+
side-note {
font-weight: normal;
font-size: 0.8em;