Browse Source

Fix style of local variable declarations

Decouple variable declarations so that each can have docstring.
In case of _relck() we also rename variable $relsrc to a more
context-specific term $oracle.
Alois Mahdal 7 years ago
parent
commit
c03e679e10
6 changed files with 114 additions and 76 deletions
  1. 28
    17
      src/include/build.sh
  2. 19
    11
      src/include/deploy.sh
  3. 14
    9
      src/include/facts.sh
  4. 23
    16
      src/include/ini.sh
  5. 8
    5
      src/include/mkit.sh
  6. 22
    18
      src/include/release.sh

+ 28
- 17
src/include/build.sh View File

8
     #
8
     #
9
     # Process one skeleton $1 of type $3 (or guessed) to path $2
9
     # Process one skeleton $1 of type $3 (or guessed) to path $2
10
     #
10
     #
11
-    local srcpath=$1
12
-    local dstpath=$2
13
-    local ftype=$3
11
+    local srcpath=$1    # skeleton path
12
+    local dstpath=$2    # destination meaty animal path
13
+    local ftype=$3      # file/builder type
14
     test -n "$dstpath"  || dstpath=${srcpath%.skel}
14
     test -n "$dstpath"  || dstpath=${srcpath%.skel}
15
     test -n "$ftype"    || ftype=$(_guess_ftype "$dstpath")
15
     test -n "$ftype"    || ftype=$(_guess_ftype "$dstpath")
16
     debug_var srcpath dstpath ftype
16
     debug_var srcpath dstpath ftype
23
     #
23
     #
24
     # Build a file of type $1; fom stdin to stdout
24
     # Build a file of type $1; fom stdin to stdout
25
     #
25
     #
26
-    local ftype=$1
26
+    local ftype=$1      # file/builder type
27
     case $ftype in
27
     case $ftype in
28
         MKIT_COMMON)    _expand_tokens "tokens" ;;
28
         MKIT_COMMON)    _expand_tokens "tokens" ;;
29
         markdown)       _expand_includes | _expand_tokens "tokens" ;;
29
         markdown)       _expand_includes | _expand_tokens "tokens" ;;
61
     #
61
     #
62
     # Read stdin, expanding tokens from sections $@
62
     # Read stdin, expanding tokens from sections $@
63
     #
63
     #
64
-    local script=$(mktemp --tmpdir mkit-tmp.XXXXXXXXXX)
65
-    local section varname varvalue
64
+    local script        # sed script cache
65
+    local section       # each section to expand tokens from
66
+    local varname       # each token name
67
+    local varvalue      # each token value
68
+    script=$(mktemp --tmpdir mkit-tmp.XXXXXXXXXX)
66
     {
69
     {
67
         for section in "$@";
70
         for section in "$@";
68
         do
71
         do
93
     #
96
     #
94
     # Guess file type from destination path $1
97
     # Guess file type from destination path $1
95
     #
98
     #
96
-    local dstpath=$1
99
+    local dstpath=$1    # destination path
97
     case $dstpath in
100
     case $dstpath in
98
         *.md) echo markdown    ;;
101
         *.md) echo markdown    ;;
99
         *)    echo MKIT_COMMON ;;
102
         *)    echo MKIT_COMMON ;;
114
     #
117
     #
115
     # Add meat to all skeletons
118
     # Add meat to all skeletons
116
     #
119
     #
117
-    local srcpath
120
+    local srcpath   # each source path
118
     find -type f -name '*.skel' \
121
     find -type f -name '*.skel' \
119
      | while read -r srcpath;
122
      | while read -r srcpath;
120
        do
123
        do
126
     #
129
     #
127
     # Build manpages using ronn
130
     # Build manpages using ronn
128
     #
131
     #
129
-    local manfile mdfile
132
+    local manfile   # each manual file listed in '[files:man]'
133
+    local mdfile    # each source markdown file
130
     if command -v ronn >/dev/null;
134
     if command -v ronn >/dev/null;
131
     then
135
     then
132
         ini lskeys "files:man" \
136
         ini lskeys "files:man" \
160
     #
164
     #
161
     # Build Debian stuff (eamed tarball, debian dir)
165
     # Build Debian stuff (eamed tarball, debian dir)
162
     #
166
     #
163
-    local version="$(semver)"
167
+    local version       # package version
168
+    local debian_skel   # 'debian' folder skeleton
169
+    local dfsrc         # each source file from ^^
170
+    local dftgt         # each built packaging file
171
+    version=$(semver)
164
 
172
 
165
     # tarball - we should already have by means of 'dist'
173
     # tarball - we should already have by means of 'dist'
166
     #
174
     #
171
 
179
 
172
     # read content of each mandatory file from debian_skel
180
     # read content of each mandatory file from debian_skel
173
     #
181
     #
174
-    local debian_skel=$(ini 1value dist:debstuff)
182
+    debian_skel=$(ini 1value dist:debstuff)
175
     test -n "$debian_skel" || die "dist:debstuff not specified"
183
     test -n "$debian_skel" || die "dist:debstuff not specified"
176
     test -d "$debian_skel" || die "debian directory template found: $debian_skel"
184
     test -d "$debian_skel" || die "debian directory template found: $debian_skel"
177
     mkdir -p debian/source
185
     mkdir -p debian/source
178
-    local dfsrc dftgt
179
     find "$debian_skel" -type f \
186
     find "$debian_skel" -type f \
180
       | while read -r dfsrc;
187
       | while read -r dfsrc;
181
         do
188
         do
193
     #FIXME: lacking Makefile skills, we do this step twice fot
200
     #FIXME: lacking Makefile skills, we do this step twice fot
194
     #       rpmstuff, hence -f hack for gzip
201
     #       rpmstuff, hence -f hack for gzip
195
     #
202
     #
196
-    local version=$(semver)
197
-    local git_lasthash=$(git_lasthash)
198
-    local dirname=$MKIT_PROJ_PKGNAME-$version
203
+    local version           # tarball version
204
+    local git_lasthash      # last git commit hash
205
+    local dirname           # directory and tarball name
206
+    version=$(semver)
207
+    dirname=$MKIT_PROJ_PKGNAME-$version
208
+    git_lasthash=$(git_lasthash)
199
     mkdir -p "$dirname"
209
     mkdir -p "$dirname"
200
     ini values "dist:tarball" | xargs -I DIST_ITEM cp -R DIST_ITEM "$dirname"
210
     ini values "dist:tarball" | xargs -I DIST_ITEM cp -R DIST_ITEM "$dirname"
201
     update_version "$version" "$dirname/mkit.ini"
211
     update_version "$version" "$dirname/mkit.ini"
212
     #
222
     #
213
     # Build specfile
223
     # Build specfile
214
     #
224
     #
215
-    local specname=$MKIT_PROJ_PKGNAME.spec
216
-    local specsrc=$(ini 1value "dist:rpmstuff")
225
+    local specname=$MKIT_PROJ_PKGNAME.spec      # .spec filename
226
+    local specsrc                               # source of specfile
227
+    specsrc="$(ini 1value "dist:rpmstuff")"
217
     test -n "$specsrc" || die "dist:rpmstuff not specified"
228
     test -n "$specsrc" || die "dist:rpmstuff not specified"
218
     test -f "$specsrc" || die "specfile template not found: $specsrc"
229
     test -f "$specsrc" || die "specfile template not found: $specsrc"
219
     _build1 "$specsrc" "$specname"
230
     _build1 "$specsrc" "$specname"

+ 19
- 11
src/include/deploy.sh View File

23
     # Directories are copied recursively, and mode is
23
     # Directories are copied recursively, and mode is
24
     # applied only to files.
24
     # applied only to files.
25
     #
25
     #
26
-    local src=$1
27
-    local dst=$2
28
-    local mode=${3:-$MKIT_DEFAULT_MODE}
26
+    local src=$1                            # source path
27
+    local dst=$2                            # destination path
28
+    local mode=${3:-$MKIT_DEFAULT_MODE}     # mode
29
+    local chmod_item                        # each file to chmod in directory
29
     if test -d "$src";
30
     if test -d "$src";
30
     then
31
     then
31
         _maybe mkdir -vp "$(dirname "$dst")"
32
         _maybe mkdir -vp "$(dirname "$dst")"
44
     #
45
     #
45
     # Find out target path for src file $2 of group $1
46
     # Find out target path for src file $2 of group $1
46
     #
47
     #
47
-    local grp=$1
48
-    local src=$2
49
-    local dst=$3
48
+    local grp=$1        # deploy group
49
+    local src=$2        # each source
50
+    local dst=$3        # alternative destination name
50
     test -n "$dst" || dst=${src##*/}
51
     test -n "$dst" || dst=${src##*/}
51
     echo "$(_get_root "$grp")/$dst"
52
     echo "$(_get_root "$grp")/$dst"
52
 }
53
 }
55
     #
56
     #
56
     # Find out target root for group $1
57
     # Find out target root for group $1
57
     #
58
     #
58
-    local grp=$1
59
-    local root=$(ini 1value "roots:$grp")
60
-    local destdir=$(ini 1value ENV:DESTDIR)
59
+    local grp=$1        # deploy group
60
+    local root          # root for this group
61
+    local destdir       # value of DESTDIR
62
+    root=$(ini 1value "roots:$grp")
63
+    destdir=$(ini 1value ENV:DESTDIR)
61
     destdir=${destdir%/}
64
     destdir=${destdir%/}
62
     case $destdir:$root in
65
     case $destdir:$root in
63
         *:)     die "missing in config.ini: roots:$grp" ;;
66
         *:)     die "missing in config.ini: roots:$grp" ;;
84
     #
87
     #
85
     # Install product
88
     # Install product
86
     #
89
     #
87
-    local dst group mode src
90
+    local group     # each deploy group
91
+    local mode      # mode (group-specific)
92
+    local src       # each source path
93
+    local dst       # each (final absolute) destination path
88
     ini lskeys "files" \
94
     ini lskeys "files" \
89
       | sort \
95
       | sort \
90
       | uniq \
96
       | uniq \
106
     #
112
     #
107
     # Uninstall product
113
     # Uninstall product
108
     #
114
     #
109
-    local dst group src
115
+    local group     # each deploy group
116
+    local src       # each source path
117
+    local dst       # each (final absolute) destination path
110
     ini lskeys "files" \
118
     ini lskeys "files" \
111
       | sort \
119
       | sort \
112
       | uniq \
120
       | uniq \

+ 14
- 9
src/include/facts.sh View File

6
     #
6
     #
7
     # Get git bool (ie. exit status counts) $1
7
     # Get git bool (ie. exit status counts) $1
8
     #
8
     #
9
-    local bool_name=$1
9
+    local bool_name=$1      # name of boolean to get
10
     git_present || warn "can't give bool outside git repo: $bool_name"
10
     git_present || warn "can't give bool outside git repo: $bool_name"
11
     case "$bool_name" in
11
     case "$bool_name" in
12
         dirty_files)
12
         dirty_files)
29
     #
29
     #
30
     # Get git fact $1
30
     # Get git fact $1
31
     #
31
     #
32
-    local fact_name=$1
32
+    local fact_name=$1      # name of fact to get
33
     git_present || warn "can't give fact outside git repo: $fact_name"
33
     git_present || warn "can't give fact outside git repo: $fact_name"
34
     case "$fact_name" in
34
     case "$fact_name" in
35
         latest_tag)
35
         latest_tag)
88
     # work if you got outside the git repo in other way than dist
88
     # work if you got outside the git repo in other way than dist
89
     # target, but that's actually expected.)
89
     # target, but that's actually expected.)
90
     #
90
     #
91
+    local last_hash     # last commit hash
91
     if git_present;
92
     if git_present;
92
     then    # we are in git repo
93
     then    # we are in git repo
93
-        local last_hash=$(git rev-parse HEAD)
94
+        last_hash=$(git rev-parse HEAD)
94
         echo -n "$last_hash"
95
         echo -n "$last_hash"
95
         git_bool dirty && echo -n ".dirty"
96
         git_bool dirty && echo -n ".dirty"
96
     else    # we are outside (eg. distributor's build dir')
97
     else    # we are outside (eg. distributor's build dir')
146
     # FIXME:  Using project:prerl for release IDs may not be compatible with
147
     # FIXME:  Using project:prerl for release IDs may not be compatible with
147
     #         release strategy implemented in release.sh
148
     #         release strategy implemented in release.sh
148
     #
149
     #
149
-    local version=$(ini 1value project:version)
150
-    local prerl=$(ini 1value project:prerl)
150
+    local version       # version string (final result)
151
+    local prerl         # pre-release keyword (from mkit.ini, eg. 'alpha')
152
+    local latest_tag    # latest git tag
153
+    local commit        # commit indicator (CURRENT_BRANCH.gHASH)
154
+    local dirty         # 0 if dirty, 1 if clean
155
+    local suffix        # version suffix
156
+    version=$(ini 1value project:version)
157
+    prerl=$(ini 1value project:prerl)
151
     grep ":" <<<"$prerl" && warn "colon in project:prerl may corrupt version data: $prerl"
158
     grep ":" <<<"$prerl" && warn "colon in project:prerl may corrupt version data: $prerl"
152
     if git_present;
159
     if git_present;
153
     then    # we are in git repo... so we can get smart
160
     then    # we are in git repo... so we can get smart
154
-        local latest_tag=$(git_fact latest_tag)
161
+        latest_tag=$(git_fact latest_tag)
155
         if ! git describe --tags --exact-match HEAD >&/dev/null;
162
         if ! git describe --tags --exact-match HEAD >&/dev/null;
156
         then    # we are at a later commit than the last tag
163
         then    # we are at a later commit than the last tag
157
-            local commit="$(git_fact current_branch).g$(git_fact latest_sha)"
164
+            commit="$(git_fact current_branch).g$(git_fact latest_sha)"
158
         fi
165
         fi
159
-        local dirty=""
160
-        local suffix=""
161
         git_bool dirty; dirty=$?
166
         git_bool dirty; dirty=$?
162
         test -n "$latest_tag" && version=${latest_tag:1}
167
         test -n "$latest_tag" && version=${latest_tag:1}
163
         case "$dirty:$commit" in
168
         case "$dirty:$commit" in

+ 23
- 16
src/include/ini.sh View File

4
     #
4
     #
5
     # A no-op for text stream
5
     # A no-op for text stream
6
     #
6
     #
7
+    local line      # each line
7
     while read -r line;
8
     while read -r line;
8
     do
9
     do
9
         printf -- "%s\n" "$line"
10
         printf -- "%s\n" "$line"
14
     #
15
     #
15
     # Expand reference value (prefix only)
16
     # Expand reference value (prefix only)
16
     #
17
     #
17
-    local line suffix ref value
18
+    local line      # each input line
19
+    local suffix    # tail of the line
20
+    local ref       # reference
21
+    local value     # value if reference
18
     while read -r line;                     # [foo:bar]/path
22
     while read -r line;                     # [foo:bar]/path
19
     do
23
     do
20
         suffix="${line#\[*\]}"              # /path
24
         suffix="${line#\[*\]}"              # /path
30
     #
34
     #
31
     # Read key from a section
35
     # Read key from a section
32
     #
36
     #
33
-    local wnt=$1
37
+    local wnt=$1    # wanted key
34
     grep '.' \
38
     grep '.' \
35
       | grep -v '\s*#' \
39
       | grep -v '\s*#' \
36
       | sed -e 's/ *= */=/; s/ +$//; s/^//;' \
40
       | sed -e 's/ *= */=/; s/ +$//; s/^//;' \
48
     #     [files:share]
52
     #     [files:share]
49
     #         my/lib.sh   = proj/my/lib.sh
53
     #         my/lib.sh   = proj/my/lib.sh
50
     #
54
     #
51
-    local wnt=$1
52
-    local wntkey=${wnt##*:}
53
-    local wntsec=${wnt%:$wntkey}
55
+    local wnt=$1                    # wanted path
56
+    local wntkey=${wnt##*:}         # ^^ key part
57
+    local wntsec=${wnt%:$wntkey}    # ^^ section part
58
+    local override                  # ENV override (only ENV section)
54
     if test "$wntsec" = 'ENV';
59
     if test "$wntsec" = 'ENV';
55
     then
60
     then
56
-        local override=${!wntkey}
61
+        override=${!wntkey}
57
         if test -n "$override";
62
         if test -n "$override";
58
         then
63
         then
59
             echo "$override"
64
             echo "$override"
67
     #
72
     #
68
     # Read one INI section
73
     # Read one INI section
69
     #
74
     #
70
-    local wnt=$1
71
-    local ok=false
75
+    local wnt=$1        # wanted section name
76
+    local ok=false      # are we in the section?
77
+    local line          # each input line
72
     grep '.' \
78
     grep '.' \
73
       | grep -v '\s*#' \
79
       | grep -v '\s*#' \
74
       | while read -r line;
80
       | while read -r line;
87
     #
93
     #
88
     # List keys from a section
94
     # List keys from a section
89
     #
95
     #
90
-    local sct=$1
96
+    local sct=$1    # section of interest
91
     _ini_grepsec "$sct" | cut -d= -f1 | sort | uniq
97
     _ini_grepsec "$sct" | cut -d= -f1 | sort | uniq
92
 }
98
 }
93
 
99
 
107
     #
113
     #
108
     # do ini operation
114
     # do ini operation
109
     #
115
     #
110
-    local op=$1
111
-    local arg=$2
112
-    local fn
113
-    local limit=_ini_cat
116
+    local op=$1             # operator
117
+    local arg=$2            # argument
118
+    local fn                # internal function implementing $op
119
+    local limit=_ini_cat    # limiting internal function
114
     case $op in
120
     case $op in
115
         lskeys) fn=_ini_lskeys   ;;
121
         lskeys) fn=_ini_lskeys   ;;
116
         sec)    fn=_ini_grepsec  ;;
122
         sec)    fn=_ini_grepsec  ;;
125
     #
131
     #
126
     # Change project.version in mkit.ini at path $2 to version $1
132
     # Change project.version in mkit.ini at path $2 to version $1
127
     #
133
     #
128
-    local version=$1
129
-    local inifile=$2
130
-    local tmp=$(mktemp -t mkit.update_version.XXXXXXXX)
134
+    local version=$1    # new version
135
+    local inifile=$2    # mkit.ini path
136
+    local tmp           # mkit.ini cache
137
+    tmp=$(mktemp -t mkit.update_version.XXXXXXXX)
131
     <"$inifile" perl -e '
138
     <"$inifile" perl -e '
132
         my $hit = 0;
139
         my $hit = 0;
133
         my $done = 0;
140
         my $done = 0;

+ 8
- 5
src/include/mkit.sh View File

38
     # Print debug message
38
     # Print debug message
39
     #
39
     #
40
     $MKIT_DEBUG || return 0
40
     $MKIT_DEBUG || return 0
41
-    local __mkit_debug_var_name__
41
+    local __mkit_debug_var_name__       # variable name to debug
42
     for __mkit_debug_var_name__ in "$@";
42
     for __mkit_debug_var_name__ in "$@";
43
     do
43
     do
44
         {
44
         {
65
     # If our x is 0, check first two fragments, otherwise check just
65
     # If our x is 0, check first two fragments, otherwise check just
66
     # the x.  Fragments must equal.
66
     # the x.  Fragments must equal.
67
     #
67
     #
68
-    local their_ver our_x our_y their_x their_y
69
-    their_ver=$1
68
+    local their_ver=$1      # their version
69
+    local our_x             # our X
70
+    local our_y             # our Y
71
+    local their_x           # their X
72
+    local their_y           # their Y
70
     their_x=${their_ver%%.*}
73
     their_x=${their_ver%%.*}
71
     their_y=${their_ver##$their_x.}
74
     their_y=${their_ver##$their_x.}
72
     their_y=${their_y%%.*}
75
     their_y=${their_y%%.*}
89
     # Look for "#mkit version=0.0.0" or similar in first or last
92
     # Look for "#mkit version=0.0.0" or similar in first or last
90
     # 3 lines of the file; then check if the version is supported.
93
     # 3 lines of the file; then check if the version is supported.
91
     #
94
     #
92
-    local ver_line
93
-    local their_ver
95
+    local ver_line      # line declaring version
96
+    local their_ver     # the declared version
94
     ver_line=$(
97
     ver_line=$(
95
         {
98
         {
96
             head -3 "$MKIT_INI"
99
             head -3 "$MKIT_INI"

+ 22
- 18
src/include/release.sh View File

7
     #
7
     #
8
     # Bump version on stdin by level $1 (x, y or z)
8
     # Bump version on stdin by level $1 (x, y or z)
9
     #
9
     #
10
-    local rlevel=$1
11
-    local old
10
+    local rlevel=$1     # release level
11
+    local old           # old version
12
+    local oldx          # ... X
13
+    local oldz          # ... Z
14
+    local oldy          # ... Y
15
+    local tmpy          # Y parsing cache
16
+    local new           # bumped version
12
     read -r old
17
     read -r old
13
-    local oldx=${old%.*.*}
14
-    local oldz=${old#*.*.}
15
-    local tmpy=${old%.*}
16
-    local oldy=${tmpy#*.}
17
-    local new=""
18
+    oldx=${old%.*.*}
19
+    oldz=${old#*.*.}
20
+    tmpy=${old%.*}
21
+    oldy=${tmpy#*.}
18
     case $rlevel in
22
     case $rlevel in
19
         x) new="$((oldx+MKIT_BUMPSIZE)).0.0"            ;;
23
         x) new="$((oldx+MKIT_BUMPSIZE)).0.0"            ;;
20
         y) new="$oldx.$((oldy+MKIT_BUMPSIZE)).0"        ;;
24
         y) new="$oldx.$((oldy+MKIT_BUMPSIZE)).0"        ;;
28
     #
32
     #
29
     # Die if blocking condition $1 is detected
33
     # Die if blocking condition $1 is detected
30
     #
34
     #
31
-    local condition=$1
32
-    local x
35
+    local condition=$1      # condition name
36
+    local oracle            # expected value
33
     case "$condition" in
37
     case "$condition" in
34
         git_present)
38
         git_present)
35
             git rev-parse HEAD >&/dev/null\
39
             git rev-parse HEAD >&/dev/null\
36
              || die "cannot do this outside git repo"
40
              || die "cannot do this outside git repo"
37
             ;;
41
             ;;
38
         at_relsrc)
42
         at_relsrc)
39
-            local relsrc=$(ini 1value project:relsrc)
43
+            oracle=$(ini 1value project:relsrc)
40
             git_fact current_branch \
44
             git_fact current_branch \
41
-              | grep -qFx "$relsrc" \
42
-             || die "you are not on release source branch: $relsrc"
45
+              | grep -qFx "$oracle" \
46
+             || die "you are not on release source branch: $oracle"
43
             ;;
47
             ;;
44
         not_dirty)
48
         not_dirty)
45
             git diff --shortstat 2>/dev/null \
49
             git diff --shortstat 2>/dev/null \
62
              && die "WIP commit since $(git_fact latest_tag)"
66
              && die "WIP commit since $(git_fact latest_tag)"
63
             ;;
67
             ;;
64
         ini_version)
68
         ini_version)
65
-            local oracle=$(git_fact latest_version | _bump_version "$rlevel")
69
+            oracle=$(git_fact latest_version | _bump_version "$rlevel")
66
             ini 1value project:version  \
70
             ini 1value project:version  \
67
               | grep -qFx "$oracle" \
71
               | grep -qFx "$oracle" \
68
              || die "new version not in mkit.ini: $oracle"
72
              || die "new version not in mkit.ini: $oracle"
83
     # FIXME: Using project:prerl as build.sh:semver() does may not be
87
     # FIXME: Using project:prerl as build.sh:semver() does may not be
84
     #        compatible with this release strategy
88
     #        compatible with this release strategy
85
     #
89
     #
86
-    local rlevel=$1
87
-    local newtag
88
-    local reldst
90
+    local rlevel=$1     # release level (x, y or z)
91
+    local newtag        # new tag
92
+    local reldst        # release destination branch (if any)
89
 
93
 
90
     _relck git_present
94
     _relck git_present
91
     _relck at_relsrc
95
     _relck at_relsrc
133
     # Perform checks, compute new version, update mkit.ini and initiate
137
     # Perform checks, compute new version, update mkit.ini and initiate
134
     # 'Bump version' commit with changelog template.
138
     # 'Bump version' commit with changelog template.
135
     #
139
     #
136
-    local rlevel=$1
137
-    local nextver   # after the bump
140
+    local rlevel=$1     # bump level (x, y or z)
141
+    local nextver       # version after the bump
138
     _relck git_present
142
     _relck git_present
139
     _relck at_relsrc
143
     _relck at_relsrc
140
     _relck not_dirty
144
     _relck not_dirty