Build.zsh

content/baguette/index.md

@@ -866,17 +866,18 @@ The most useful contributions right now would be to provide new service configur
 
 <a name="build.zsh"></a>
 ### [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.
+A `Makefile` is very useful to share your project, <u>whatever your project is</u>.
+No matter if it is an application or a library, whatever the language used, etc.
 
 Build.zsh creates a makefile from a simple declarative configuration file.
 A `Makefile` should:
 - **compile and link the application**
-- **handle dependencies** and **rebuild only updated parts of the application** *for incremental builds*
+- **handle dependencies** and **rebuild only the updated parts of the application** *for incremental builds*
-- **allow users to rebuid any part of your project independently**
+- **allow users to rebuild any part of the project independently**
 - **install the application**<br />
-  The default installation root directory is `/usr/local` but you should be able to change that easily (with an environment variable or through configuration).
+  The default installation root directory is `/usr/local` but it can be changed easily (with an environment variable or through configuration).
 - **create a tarball of the project**<br />
-	This tarball includes your application, its man-pages, the Makefile to build it, etc.
+	This tarball includes the application, its man-pages, the Makefile to build it, etc.
 - **have a `make help`** *everybody needs help*
 - *(BONUS)* have colors. I like colors.
 
@@ -893,7 +894,7 @@ $ ls Makefile     # tadaaaaa you made a Makefile
 Makefile
 ```
 
-You can invoke your newly created Makefile with `make help` to know what can it do for you.
+You can invoke your newly created Makefile with `make help` to know what it can do for you.
 For example, it can create a tarball with `make dist`.
 
 **How-to make a `project.zsh` for `build.zsh`**
@@ -903,26 +904,26 @@ For example, it can create a tarball with `make dist`.
 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 = all the applications to compile in the project.
 targets=(my-application)
 
-# Then, we tell the language of these applications.
+# The language of these applications is then specified.
 # 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
+# `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
+# The sources of the application.
 sources[my-application]=src/main.cr
 
-# The application depends on a number of files.
+# The application depends on a certain number of files.
-# Each modification of one of these files = we have to re-compile.
+# `make` will re-compile "my-application" if one of these files is modified.
 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`).
+# Finally, the list of the files to be included in the tarball (made through `make dist`).
-# Here, we want to provide in our tarball:
+# Here, the tarball will include:
 #   the application binary,
 #   man-pages in man/ directory,
-#   this project.zsh and the generated Makefile
+#   this project.zsh and the generated Makefile.
 dist=(my-application man/*[1-9] project.zsh Makefile)
 ```
 
@@ -956,33 +957,34 @@ dist=(build.zsh.in build/*.zsh project.zsh Makefile)
 This time, we want to build a Makefile for a C library.
 
 ```zsh
-package=libipc    # Package name.
+package=libipc    # Name of the package.
-version=0.5.1     # Package version.
+version=0.5.1     # Version of the package.
 
 # 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:
+# The `library` type automatically adds two 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)"
+sources[libipc]=$(ls src/*.c)
 
 depends[libipc]=$(ls src/*.h)
 
-# We need to add extra compilation flags.
+# 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`.
+# The man/libipc.7 target is a man-page 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`.
+# Files to add 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.
@@ -995,7 +997,7 @@ This `project.zsh` comes from the [LibIPC repository][libipc] (a library we'll s
 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?
+You like the functionalities we presented here, but you want an alternative to Makefiles?
 <red>We may add some other back-ends.</red>
 Stay tuned!