1GRINDPERL(1)          User Contributed Perl Documentation         GRINDPERL(1)
2
3
4

NAME

6       grindperl - Command-line tool to help build and test bleadperl
7

VERSION

9       version 0.004
10

SYNOPSIS

12       These commands are intended to be run from within a clone of the Perl
13       git repository.
14
15         # Configure && make && make test (in parallel)
16         $ grindperl
17
18         # Configure && make && make test_porting (in parallel)
19         $ grindperl --porting
20
21         # Same as first example, but without threads
22         $ grindperl --no-threads
23
24         # Configure/make/test and install
25         $ grindperl --prefix=/opt/perl/blead --install
26

DESCRIPTION

28       Hacking on the Perl source tree requires one to regularly build and
29       test.  The "grindperl" tool helps automate some common configuration,
30       build and test tasks.  Most Perl 5 porters have written something like
31       this and I'm putting mine on CPAN to help new (or less automated)
32       contributors.
33
34       Instead of typing this:
35
36         $ ./Configure -des -Dusedevel -Dcc='ccache=gcc' \
37           -Dprefix=/tmp/blead-$(git describe) -DDEBUGGING \
38           -Dusethreads
39         $ make -j 9 test_prep
40         $ TEST_JOBS=9 make test_harness
41
42       You can just type this:
43
44         $ grindperl
45
46       If you want to run "make test_porting" before committing or before
47       merging a submitted patch -- which is strongly encouraged -- that is as
48       easy as:
49
50         $ grindperl --porting
51
52       Generally, the following steps are taken (unless modified by options):
53
54       ·   clean the source directory, with "git clean -dxf" or "make
55           distclean"
56
57           as necessary
58
59       ·   run "Configure" with desired options
60
61       ·   run either "make test_harness" or "make test_porting" or "make
62           test_prep"
63
64           depending on various options
65
66       If anything fails along the way, "grindperl" will stop with an error
67       message.
68

OPTIONS

70       Any boolean options that default to true may be negated by prefixing
71       their long form with "no-", e.g. "--no-threads".
72
73   --config
74       Boolean flag.  When set, "grindperl" will halt after running
75       "Configure".  Default is false.
76
77   --jobs=N or -j N
78       Controls how many parallel make jobs to run.  Defaults to 9.
79
80   --testjobs=N or -t N
81       Controls the number of parallel test jobs to run.  Defaults to 9.
82       Setting this to 0 will run "make test_prep" but will not run tests.
83
84   --porting
85       Boolean flag.  When set, "make test_porting" will be run instead of
86       "make test_harness".  The number of jobs to run in parallel will still
87       be based on the "--testjobs" option.  Default is false.
88
89   --install
90       Boolean flag.  When set, "grindperl" will run "make install" after all
91       other steps.  Be sure to set "--prefix" to a writeable destination.
92       Default is false.
93
94   --output FILE or -o FILE
95       Instructs "grindperl" to merge STDERR and STDOUT and redirect output to
96       the given file to capture build/test results.
97
98   --prefix PATH
99       Sets an explicit installation path via "-Dprefix=...".
100
101       If not set, a default prefix will be calculated relative to
102       "--install_root".
103
104       If a ".git" directory exists, the prefix will resemble
105       "ROOT/BRANCH-DESCRIBE" if a branch can be determined or
106       "ROOT/fromgit-DESCRIBE" if the branch cannot be determined (as from a
107       detached HEAD).  E.g. given the default "--install_root" of "/tmp", the
108       prefix for the blead branch might resemble this:
109
110         /tmp/blead-v5.15.1-22-g5213914
111
112       This ensures the the prefix is different for different places in the
113       commit history.
114
115       If there is no ".git" directory, then the prefix will resemble
116       "ROOT/DIRNAME-EPOCH" where DIRNAME is the name of the current directory
117       and EPOCH is the number of epoch seconds.
118
119         /tmp/perl-5.15.1-1311278560
120
121       These prefix choices ensure that installing different grindperl runs
122       will generally not clobber each other.
123
124   --install_root
125       A base path for a generated default "--prefix". The default install
126       root is "/tmp".  This needs to be a directory for which you have write
127       permissions.
128
129   --debugging
130       Boolean flag.  Sets "-DDEBUGGING".  Default is true.
131
132   --threads
133       Boolean flag.  Sets "-Dusethreads".  Default is true.
134
135   --cache
136       Boolean flag.  When true, "grindperl" will save your "config.sh" and
137       "Policy.sh" files to a hidden cache file.  If these files exist, it
138       will restore them and run "Configure" with the "-r" option.
139
140       Using cached config files from a different commit can break things and
141       is not recommended.
142
143       Defaults to false.
144
145   --man
146       Boolean flag.  When false, "grindperl" will disable man directories and
147       man files will not be generated or installed.  Defaults to false.
148
149   --verbose or -v
150       Outputs some extra progress messages and warnings.
151
152   --define KEY=VALUE or -D KEY=VALUE
153   --undefine KEY or -U KEY
154   --additions KEY=VALUE or -A KEY=VALUE
155       May be specified multiple times with different values of KEY.  These
156       set the "-D", "-U" and "-A" options for "Configure".  Note that unlike
157       "Configure", these require a space between the option and the key or
158       key/value pair.
159
160   --32 (EXPERIMENTAL)
161       This experimental flag tries to force as much 32-bitness as possible,
162       even on a 64 bit operating system.  It's very hacky, messes with
163       compiler and linker flags and is not guaranteed on all platforms.
164

CONFIGURATION FILE

166       You can put command line options into a configuration file, one per
167       line, and they will be prepended to @ARGV before options are processed.
168       For example, here is what I have in my config file.
169
170           --install_root=/opt/perl
171           -D cc='ccache gcc'
172           -D cf_by=dagolden
173           -D cf_email='dagolden@cpan.org'
174           -D perladmin='dagolden@cpan.org'
175           -D optimize=-g
176           -A ccflags=-DPERL_USE_SAFE_PUTENV
177
178       To edit the config file, be sure your "EDITOR" environment variable is
179       set and then run "grindperl --edit".
180

CAVEATS

182       ·   You must have git installed and in your path
183
184       ·   This depends on certain shell redirection constructs and is
185           unlikely to work on non-POSIX systems
186

AUTHOR

188       David Golden <dagolden@cpan.org>
189
191       This software is Copyright (c) 2011 by David Golden.
192
193       This is free software, licensed under:
194
195         The Apache License, Version 2.0, January 2004
196
197
198
199perl v5.28.1                      2015-12-09                      GRINDPERL(1)
Impressum