1GRINDPERL(1) User Contributed Perl Documentation GRINDPERL(1)
2
6 grindperl - Command-line tool to help build and test bleadperl
7
9 version 0.004
10
12 These commands are intended to be run from within a clone of the Perl
13 git repository.
14 # Configure && make && make test (in parallel)
16 $ grindperl
17 # Configure && make && make test_porting (in parallel)
19 $ grindperl --porting
20 # Same as first example, but without threads
22 $ grindperl --no-threads
23 # Configure/make/test and install
25 $ grindperl --prefix=/opt/perl/blead --install
26
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 Instead of typing this:
35 $ ./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 You can just type this:
43 $ grindperl
45 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 $ grindperl --porting
51 Generally, the following steps are taken (unless modified by options):
53 • clean the source directory, with "git clean -dxf" or "make
55 distclean"
56 as necessary
58 • run "Configure" with desired options
60 • run either "make test_harness" or "make test_porting" or "make
62 test_prep"
63 depending on various options
65 If anything fails along the way, "grindperl" will stop with an error
67 message.
68
70 Any boolean options that default to true may be negated by prefixing
71 their long form with "no-", e.g. "--no-threads".
72 --config
74 Boolean flag. When set, "grindperl" will halt after running
75 "Configure". Default is false.
76 --jobs=N or -j N
78 Controls how many parallel make jobs to run. Defaults to 9.
79 --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 --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 --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 --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 --prefix PATH
99 Sets an explicit installation path via "-Dprefix=...".
100 If not set, a default prefix will be calculated relative to
102 "--install_root".
103 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 /tmp/blead-v5.15.1-22-g5213914
111 This ensures the the prefix is different for different places in the
113 commit history.
114 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 /tmp/perl-5.15.1-1311278560
120 These prefix choices ensure that installing different grindperl runs
122 will generally not clobber each other.
123 --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 --debugging
130 Boolean flag. Sets "-DDEBUGGING". Default is true.
131 --threads
133 Boolean flag. Sets "-Dusethreads". Default is true.
134 --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 Using cached config files from a different commit can break things and
141 is not recommended.
142 Defaults to false.
144 --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 --verbose or -v
150 Outputs some extra progress messages and warnings.
151 --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 --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
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 --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 To edit the config file, be sure your "EDITOR" environment variable is
179 set and then run "grindperl --edit".
180
182 • You must have git installed and in your path
183 • This depends on certain shell redirection constructs and is
185 unlikely to work on non-POSIX systems
186
188 David Golden <dagolden@cpan.org>
189
191 This software is Copyright (c) 2011 by David Golden.
192 This is free software, licensed under:
194 The Apache License, Version 2.0, January 2004
196perl v5.38.0 2023-07-20 GRINDPERL(1)