The simplest way to invoke Cows-mkgen is as follows:
cows-mkgen
Cows-mkgen analyzes the current directory and all its subdirectories recursively, parses all Cows sources and writes a makefile within the current directory.
Important: Cows-mkgen perform the same syntax check as Cows, but it doesn't check for file existence, unless it needs to parse them.
As an example, if you try to include a non existent external script with the include() statement, Cows-mkgen will try to open it to find dependencies and raise an error. On the other hand, if you use the fsize() function to get the size of an external file, Cows-mkgen won't' check if it exists or not since it's outside its tasks. Of course, when you run Make and Cows finds out about the lack of this file, it will correctly raise a warning.
Cows-mkgen supports both traditional single-letter options and mnemonic long option names. Abbreviations for option names are allowed as long as they are unique. The following are equivalent.
cows-mkgen -p../some_dir cows-mkgen --prefix ../some_dir cows-mkgen --prefix=../some_dir
Here is a list of options that can be used with Cows-mkgen, alphabetized by short option.
Display informations about accessibility issues related to Cows-mkgen.
Display output in a compact format. The amount of messages won't change, they will only be shorter. Visually impaired users relying on a speech version of shell's output may find this flag useful since large amounts of output can slow down work.
directory, --root-dir=directorySet site's root directory; Cows-mkgen will look for Cows sources within this directory and its subdirectories.
Stop execution after first warning (default behavior is to give an advice and continue running). It can be useful when your site has been released (I hope no warning will be present at that stage) and you want to be sure to catch any inaccuracy during maintenance and upgrading.
Note: Added in G-Cows version 1.7
Use 'fast' scanning mode: cows-mkgen will be about one order of magnitude faster. NOTE: this mode requires some precautions. SIMPLY USING THE '--fast' FLAG ON PREEXISTING PROJECTS CAN LEAD TO WRONG MAKEFILES. Read the documentation for details.
Display help message and exit.
Keep running after errors.
option, --cows-option=optionWhen creating makefile, add option to Cows' command-line
options.
directory, --prefix=directoryMakefile is created so that output files will be created in directory. This option can be useful in order to keep sources and
output separated.
Same as `--silent'.
extension, --source-extension=extensionSet the extension for input files; by default Cows-mkgen looks for files with .cws extension.
Don't print informational messages.
extension, --target-extension=extensionSet the extension for output files; by default the generated makefile creates output files with extension .html.
Display the version number of Cows and exit.
Produce a more verbose description.
Many command line options for Cows-mkgen can be replaced by directives in the so called options file. As an example, if you often run:
cows-mkgen --brief --cows-option="--report rep.txt" --prefix=../target
you'll probably prefer to create a Makefile.cm like this:
brief: cows-option:--report rep.txt prefix:../target
and then simply run:
cows-mkgen
When you run Cows-mkgen, it:
scans a file located in sites' root directory having the same name as the makefile it's going to create (Makefile.cm if creating Makefile, MAKEFILE.cm if creating MAKEFILE and so on ...).
parses command line options
In case of conflict between a directive within options file and a command line option, the latter is used. So, you can think about options files as an easy way to set a default behavior for Cows-mkgen, and use command line options to change it.
In case of conflict between two command line options or between two directives, Cows-mkgen exits with a fatal error.
Options without arguments are replaced by the name of the long option followed by semicolons (no whitespaces).
brief:
fatal-warnings:
ignore-errors:
quiet:
silent:
verbose:
fast:
Options with arguments are replaced by the name of the long option followed by semicolons and argument (no whitespaces).
prefix:directory
source-extension:extension
target-extension:extension
cows-option:option
Some command line options have no corresponding directive since they would be meaningless (-help, -version, -root-dir ...).
Options files also allow to create branch sites; we'll talk about this later in the manual (see Section 6.8).
If you know Makefile's syntax you can add a portion of hand written makefile to the generated one. Simply create a file named after the generated makefile with a .add suffix (by default Cows-mkgen creates a file called Makefile so simply call the additional one Makefile.add). Cows-mkgen will find it and copy it after dependencies, just before PHONY targets.
cows-mkgen
Reads Makefile.cm (if exists), analyzes current directory and all its subdirectories, and creates a makefile called Makefile. This makefile suffices the rules you need to create your site within current directory (unless directives within Makefile.cm change this behavior).
cows-mkgen -prefix=../target
Reads Makefile.cm (if exists), analyzes current directory and all its subdirectories, and creates a makefile called Makefile. This makefile suffices the rules you need to create your site within directory ../target. This helps to keep sources and generated files separated but you need some tricks to really achieve this separation (see Section 6.5).
The same result can be reached by simply running cows-mkgen if Makefile.cm contains the directive: prefix:../target.
cows-mkgen -root-dir=../site
Reads ../site/Makefile.cm (if exists), then analyzes directory ../site and all its subdirectories, and creates a makefile called Makefile. This makefile suffices the rules you need to create your site within current directory. This is another way to keep sources and generated files separated but makefile is created within current directory; the previous invocation allows to keep makefile within sources. Again, see Section 6.5 for further notes on this topic.
cows-mkgen -root-dir=../site -prefix=../target MAKEFILE
Reads ../site/MAKEFILE.cm (if exists), then analyzes directory ../site and all its subdirectories, and creates a makefile called MAKEFILE. This makefile suffices the rules you need to create your site within directory ../target.
I don't like this combination; still, if you're working with many sites and you want to group all makefiles together, this may be the right choice; of course you need to use different names for the makefiles.
cows-mkgen -cows-option="-report=\"report.txt\""
Adds -report="report.txt" to Cows' options within generated makefile; notice the backslashes used to escape quotes.
This manual can be downloaded from http://www.g-cows.org/.