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