Makefile rules & recipes

Recipes for the rules defined in your Makefiles require specific indentation. Each line in a recipe (i.e. “tests” below) must start with a tab character.

You can run:

cat -n -E -T Makefile
option description
n Show line numbers
e equivalent to -vE
t equivalent to -vT
E, –show-ends display $ at end of each line
T, –show-tabs display TAB characters as ^I
v, –show-nonprinting use ^ and M- notation, except for LFD and TAB

Which produces something like:

include ../Makeconfig$
$
headers := time.h sys/time.h sys/timeb.h bits/time.h^I^I^I\$
^I   bits/types/clockid_t.h bits/types/clock_t.h^I^I^I\$
^I   bits/types/struct_itimerspec.h^I^I^I^I\$
^I   bits/types/struct_timespec.h bits/types/struct_timeval.h^I\$
^I   bits/types/struct_tm.h bits/types/timer_t.h^I^I^I\$
^I   bits/types/time_t.h$
$
routines := offtime asctime clock ctime ctime_r difftime \$
^I    gmtime localtime mktime time^I^I \$
^I    gettimeofday settimeofday adjtime tzset^I \$
^I    tzfile getitimer setitimer^I^I^I \$
^I    stime dysize timegm ftime^I^I^I \$
^I    getdate strptime strptime_l^I^I^I \$
^I    strftime wcsftime strftime_l wcsftime_l^I \$
^I    timespec_get$
aux :=^I    era alt_digit lc-time-cleanup$
$
tests := test_time clocktest tst-posixtz tst-strptime tst_wcsftime \$
^I   tst-getdate tst-mktime tst-mktime2 tst-ftime_l tst-strftime \$
^I   tst-mktime3 tst-strptime2 bug-asctime bug-asctime_r bug-mktime1 \$
^I   tst-strptime3 bug-getdate1 tst-strptime-whitespace tst-ftime \$
^I   tst-tzname$
$

Where ^I represents a tab character and $ represents a newline character. You can use this to check for valid tab and newline indentation in your recipes in case you run into this error: *** missing separator. Stop.
If you’re using vi, make sure to use :set noet to disable replacement of tabs with a tabwidth set number of spaces.

Advertisements

Contributing to open source project – npm mysql packages.json

I chose the npm mysql package to contribute to. In this post, I will go over the steps I took for contributing a minor fix to an open source project, using a Linux terminal, Vi editor and Git.

Review Process

Looking at the package.json file, I noticed that the repository field URL did not contain an absolute URL path.  So I ran the file through the package-json-validator:

package-json_result

The validator also recommends to include the “keywords” and “bugs” fields.  I read over the official npm documentation to see how to properly write these fields in package.json.

Repository:

"repository" :
  { "type" : "git",
    "url" : "https://github.com/npm/npm.git"
  }

Keywords: An array of strings to help developers find the package using ‘npm search’.

Bugs:

{
  "url" : "https://github.com/owner/project/issues",
  "email" : "project@hostname.com"
}

I can adjust the fields now to match these formats.

Adding my changes

  • Fork repository from https://github.com/mysqljs/mysql
  • Clone project to my local workspace: git clone git@github.com:lkisac/mysql.git
  • I used Vim editor to edit the package.json file: vi packages.json
  • Adjust repository URL to:
    "repository": {
      "type": "git",
      "url": "http://github.com/mysqljs/mysql"
    },
    
  • Add change to git staging: git add package.json
  • I thought it might be a good idea to keep this change separate from the “keywords + bugs” fields change for the sake of having separate commit messages for each, so I committed this change first: git commit -m "replaced repository url with valid repository url and type"

  • Then back to editing package.json in vi to add the “keywords” and “bugs” fields:
"keywords": [
  "mysql",
  "sql",
  "database",
  "query"
],
"bugs": "http://github.com/mysqljs/mysql/issues",

Since I only included the issues URL in the bugs field, I followed the suggestion in npm of having it as only a single string instead of an object.

  • Add change: git add package.json
  • Commit change: git commit -m "added keywords + bugs url"
  • View changes in commits before pushing to repo: git show

After running git show, I noticed the indentation was off (4 spaces instead of 2) on the “sql” keyword line.  I had already set my tabwidth setting to 2, but found out that this setting does not insert spaces in replacement of a tab character. To do this you have to set the shiftwidth and set expandtab. So I added these two lines to my ~/.vimrc file (as root user, or in Fedora /etc/vimrc):


:set shiftwidth=2
:set expandtab

I switched back to my regular user and opened the package.json file again in vi.  If I press enter now from the “mysql” line, vi now automatically inserts 2 spaces at the beginning of the line.  To double check this, after hitting enter you can backspace and notice the cursor now moves back one space instead of the tabwidth’s set number of spaces.

An alternate quick fix for this of course would be to use a regular expression substitution in vi on lines 13 to 23:

:13,23s/\t/  /g

This will replace all tab characters with two spaces from lines 13 to 23.

Continuing with my changes… now I save these changes and exit vi CTRL + ZZ

  • See if changes are correct: git diff package.json
  • Spaces look good now, so I can add my changes: git add package.json
  • Commit changes to git: git commit -m "fixed vi indent to 2 spaces for sql keyword"

Now looking at the last three commits I made, I figured since the latest commit was only a minor fix to the previous, I wanted to have the two as only one commit.

git log --max-count 3

git_last_3_commits_combine

You can do this with a “git rebase”:

git rebase --interactive HEAD~2

This opens the git rebase file:

git_rebase_start

Here I want to pick the “added keywords + bugs url” as the main commit, and squash the “fixed vi indent…” commit into the main commit.

git_rebase_squash

Now I can hit Shift + ZZ to save my changes and exit git rebase.

Git now displays the combination of commit messages:

git_rebase_commit_msg

Since I want to only use the “added keywords + bugs url” commit message, I can delete the 2nd commit message.

git_rebase_new_commit_msg

Hit Shift + ZZ again to save the changes and exit.

Now the “fixed vi indent…” commit has been squashed with the “added keywords + bugs url” commit as one commit.

git_final_squash_log

Now I can push to the remote repository:
git push

One thing to note, as mentioned in github regarding git rebase, if the commits you squashed locally were previously already pushed to your remote repository, you would have to run:

git push origin branch-name --force

Although you have to be careful when choosing to do a rebase on already pushed commits and make sure they have not been reviewed or used in any way.  Use –force only only for very recent commits.

Creating Pull Request

Create the pull request by clicking the ‘Create pull request’ button in GitHub, then write a description of the changes you’ve made and create the new pull request.

pull_request_checks

Pull Request Review

One of the collaborators were quick to respond within 3 minutes of the pull request.  It was noted that npm automatically populates these fields now so adjusting the packages.json file is not necessary.  The new npm also no longer uses the keywords array in the search and the validator URL is also valid as a shortcut URL for git.

So I ended up creating a new issue for the validator-tool and the maintainer confirmed that the validator is slightly outdated and said they would be looking into updating it when they had the chance.

Vi settings

Show Line Numbers:

:set nu

Set tab size:

:set tabstop=4

Turn off word wrap:

:set nowrap

To permanently use these settings:
Add the lines to ~/.exrc (or ~/.vimrc) file

vi ~/.exrc