docs/goals.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 goals - an experimental tool that generalizes “make”
   6
   7 =head1 SUMMARY
   8
   9  goals ['TARGET'] ['VAR=VALUE']
  10        [-C|--directory DIRECTORY] [-d] [-f|--file Goalfile]
  11        [-I|--include DIRECTORY] [-j|--jobs JOBS] [--no-prelude]
  12        [-k|--keep-going] [-s|--silent|--quiet]
  13
  14  goals --help
  15
  16  goals -v|--version
  17
  18 =head1 DESCRIPTION
  19
  20 Goals is a command line tool similar in concept to L<make(1)> — a way
  21 to express dependencies between tasks that need to be done.  Goals
  22 generalizes make so it can express dependencies between not just files
  23 but anything such as URLs, remote files, remote builds and more.  It
  24 is also very extensible using only shell scripting, and it fixes many
  25 problems that make suffers from.
  26
  27 This manual page documents the command line tool and options.
  28
  29 There is an introduction to and tutorial on writing goal files, as
  30 well as a reference manual in L<Goalfile(5)>.
  31
  32 =head1 OPTIONS
  33
  34 =over 4
  35
  36 =item B<-h>
  37
  38 =item B<--help>
  39
  40 Display short help summary and exit.
  41
  42 =item B<-C> DIRECTORY
  43
  44 =item B<--directory> DIRECTORY
  45
  46 When goals starts up, and before reading the initial F<Goalfile> or
  47 doing any other processing, goals changes directory.
  48
  49 =item B<-d>
  50
  51 Enable very verbose debugging.
  52
  53 =item B<-f> GOALFILE
  54
  55 =item B<--file> GOALFILE
  56
  57 Set the name of the initial goal file to read.  The default name is
  58 F<Goalfile>.
  59
  60 Note that if a relative path is given here, it is relative to the
  61 directory specified with the I<-C> option, or to the current directory
  62 if I<-C> was not used.
  63
  64 =item B<-I> DIRECTORY
  65
  66 =item B<--include> DIRECTORY
  67
  68 Specify an include directory, used when including goal files using the
  69 C<include> directive.  You can use this option multiple times.  Later
  70 directories have priority over earlier ones.  There is also an
  71 implicit C<%stdlib> directory which is used for prelude files.
  72
  73 Note that if a relative path is given here, it is relative to the
  74 directory specified with the I<-C> option, or to the current directory
  75 if I<-C> was not used.
  76
  77 =item B<-j> JOBS
  78
  79 =item B<--jobs> JOBS
  80
  81 Set the maximum number of commands that can run at the same time.
  82 Unlike make, goals defaults to running in parallel, setting the
  83 default to the number of cores on the machine.  To disable parallel
  84 jobs, you must use S<I<-j 1>>.
  85
  86 =item B<--no-prelude>
  87
  88 Do not load F<prelude.gl> from C<%stdlib>.  The default is that the
  89 prelude is always loaded automatically before any initial goal file
  90 (but you can redefine prelude definitions in your goal file if you
  91 want).
  92
  93 =item B<-k>
  94
  95 =item B<--keep-going>
  96
  97 Continue as much as possible after an error.  The target that failed
  98 and anything that depends on that target (recursively) will fail and
  99 the program as a whole will still exit with an error, but as many
 100 targets as can be built will be built.
 101
 102 =item B<-s>
 103
 104 =item B<--silent>
 105
 106 =item B<--quiet>
 107
 108 Don't print the shell commands that are run.  This is the same as
 109 turning all S<C<{ CODE }>> sections into S<C<@{ CODE }>> sections.
 110
 111 =back
 112
 113 =head1 SEE ALSO
 114
 115 L<Goalfile(5)>, L<make(1)>.
 116
 117 =head1 AUTHORS
 118
 119 Richard W.M. Jones <rjones@redhat.com>
 120
 121 =head1 COPYRIGHT
 122
 123 Copyright (C) 2020 Richard W.M. Jones
 124
 125 Copyright (C) 2020 Red Hat Inc.
 126
 127 This program is free software; you can redistribute it and/or modify
 128 it under the terms of the GNU General Public License as published by
 129 the Free Software Foundation; either version 2 of the License, or
 130 (at your option) any later version.
 131
 132 This program is distributed in the hope that it will be useful,
 133 but WITHOUT ANY WARRANTY; without even the implied warranty of
 134 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 135 GNU General Public License for more details.
 136
 137 You should have received a copy of the GNU General Public License along
 138 with this program; if not, write to the Free Software Foundation, Inc.,
 139 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.