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        [-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 and tutorial on writing goal files:
  30 L<Goalfile(5)>.
  31
  32 There is also a reference manual: L<goals-reference(5)>.
  33
  34 =head1 OPTIONS
  35
  36 =over 4
  37
  38 =item B<-h>
  39
  40 =item B<--help>
  41
  42 Display short help summary and exit.
  43
  44 =item B<-C> DIRECTORY
  45
  46 =item B<--directory> DIRECTORY
  47
  48 When goals starts up, and before reading the initial F<Goalfile> or
  49 doing any other processing, goals changes directory.
  50
  51 =item B<-d>
  52
  53 Enable very verbose debugging.
  54
  55 =item B<-f> GOALFILE
  56
  57 =item B<--file> GOALFILE
  58
  59 Set the name of the initial goal file to read.  The default name is
  60 F<Goalfile>.
  61
  62 Note that if a relative path is given here, it is relative to the
  63 directory specified with the I<-C> option, or to the current directory
  64 if I<-C> was not used.
  65
  66 =item B<-I> DIRECTORY
  67
  68 =item B<--include> DIRECTORY
  69
  70 Specify an include directory, used when including goal files using the
  71 C<include> directive.  You can use this option multiple times.  Later
  72 directories have priority over earlier ones.  There is also an
  73 implicit C<%stdlib> directory which is used for prelude files (see
  74 L<goals-reference(5)>).
  75
  76 Note that if a relative path is given here, it is relative to the
  77 directory specified with the I<-C> option, or to the current directory
  78 if I<-C> was not used.
  79
  80 =item B<-j> JOBS
  81
  82 =item B<--jobs> JOBS
  83
  84 Set the maximum number of commands that can run at the same time.
  85 Unlike make, goals defaults to running in parallel, setting the
  86 default to the number of cores on the machine.  To disable parallel
  87 jobs, you must use S<I<-j 1>>.
  88
  89 =item B<--no-prelude>
  90
  91 Do not load F<prelude.gl> from C<%stdlib>.  The default is that the
  92 prelude is always loaded automatically before any initial goal file
  93 (but you can redefine prelude definitions in your goal file if you
  94 want).
  95
  96 =item B<-s>
  97
  98 =item B<--silent>
  99
 100 =item B<--quiet>
 101
 102 Don't print the shell commands that are run.  This is the same as
 103 turning all S<C<{ CODE }>> sections into S<C<@{ CODE }>> sections.
 104
 105 =back
 106
 107 =head1 SEE ALSO
 108
 109 L<Goalfile(5)>, L<goals-reference(5)>, L<make(1)>.
 110
 111 =head1 AUTHORS
 112
 113 Richard W.M. Jones <rjones@redhat.com>
 114
 115 =head1 COPYRIGHT
 116
 117 Copyright (C) 2020 Richard W.M. Jones
 118
 119 Copyright (C) 2020 Red Hat Inc.
 120
 121 This program is free software; you can redistribute it and/or modify
 122 it under the terms of the GNU General Public License as published by
 123 the Free Software Foundation; either version 2 of the License, or
 124 (at your option) any later version.
 125
 126 This program is distributed in the hope that it will be useful,
 127 but WITHOUT ANY WARRANTY; without even the implied warranty of
 128 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 129 GNU General Public License for more details.
 130
 131 You should have received a copy of the GNU General Public License along
 132 with this program; if not, write to the Free Software Foundation, Inc.,
 133 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.