build.zsh improved + sass (blue).

master
Philippe PITTOLI 2020-04-27 03:56:40 +02:00
parent b469fec7d4
commit 70cdcc011e
2 changed files with 105 additions and 18 deletions

View File

@ -829,31 +829,68 @@ The most useful thing to do right now is to provide new services.
<a name="build.zsh"></a> <a name="build.zsh"></a>
### [Build.zsh][build.zsh]: makefile creation. <side-note>*for mere mortals*</side-note> ### [Build.zsh][build.zsh]: makefile creation. <side-note>*for mere mortals*</side-note>
A `Makefile` is very useful to share your project, <u>whatever your project is</u>, no matter if it is an application, a library, the language used, etc.
Build.zsh creates a makefile from a simple declarative configuration file. Build.zsh creates a makefile from a simple declarative configuration file.
A `Makefile` should: A `Makefile` should:
- **build the application**<br /> - **compile and link the application**
This means a few things: - **handle dependencies** and **rebuild only updated parts of the application** *for incremental builds*
- compile and link your applications - **allow users to rebuid any part of your project independently**
- 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
- **install the application**<br /> - **install the application**<br />
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**<br /> - **create a tarball of the project**<br />
Very useful to share your project, <u>whatever your project is</u>. This tarball includes your application, its man-pages, the Makefile to build it, etc.
No matter if it is an application, a library, the language used, etc. - **have a `make help`** *everybody needs help*
- **have a `make 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 ```zsh
package=my-application $ ls project.zsh # we need to create this file, we'll cover that in a moment
version=2.18.3 project.zsh
```
# target = all the ```zsh
target=() $ 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 ```zsh
package=build_zsh # Name of the package. package=build_zsh # Name of the package.
version=0.2.1 # Version 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) dist=(build.zsh.in build/*.zsh project.zsh Makefile)
``` ```
Don't like Makefiles? <red>We may even add some other back-ends.</red> **Another real-life example** *I like examples*<br />
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?**<br />
Now you do not have any good reason avoiding Makefiles for your projects!
***But, I don't like Makefiles!***<br />
You like the functionalities we presented here, but you want an alternative to the Makefile?
<red>We may add some other back-ends.</red>
Stay tuned!
[Back to top](#top) [Back to top](#top)

View File

@ -18,6 +18,11 @@ red {
font-weight: bold; font-weight: bold;
} }
blue {
color: blue;
font-weight: bold;
}
side-note { side-note {
font-weight: normal; font-weight: normal;
font-size: 0.8em; font-size: 0.8em;