Testing and Development Tools and Tips

This is a collection of helpful tools and tips for navigating the OpenSSL code base and managing a local git repository.

Testing Environment and Tools

In the test-util branch of Mike Bland's fork are a few helper files that you may wish to copy or pull into your branch. As they are incorporated into the main OpenSSL repository, links to the mainline versions will be incorporated into the descriptions below. However, there may be newer versions in Mike's fork.

test/testutil.h

test/testutil.h defines the generic SETUP_TEST_FIXTURE and EXECUTE_TEST macros. The header comments describe how to define test-specific macros based on these.

test/new-test.sh

Generates a new automated test stub, following the Pseudo-xUnit Pattern and using the macros from test/testutil.h. The generated stub will compile standalone.

test/test_env.bash

Environment variables, functions, and aliases to help with OpenSSL unit testing. The header comments contain documentation on each of the functions and aliases in the file.

Cscope

Cscope is a powerful C source code browser. Once you have it installed, you can use the make-cscope and open-cscope functions from test/test_env.bash.

Vim Integration

Once $CSCOPE_DB (defined in test/test_env.bash is built using make-cscope, you can take advantage of the Cscope integration in Vim by adding something like the following to your .vimrc:

" Detect whether cscope features are present and whether we should add a
" connection to an existing cscope.out database file
if has("cscope")
  set nocsverb
  if filereadable("./cscope.out")
    cs add cscope.out
  elseif $CSCOPE_DB != ""
    if filereadable($CSCOPE_DB)
      cs add $CSCOPE_DB
    else
      echo "Can't read $CSCOPE_DB; cscope add not run"
    endif
  endif
  set csre
  set csverb
endif

Ctags

Ctags generates an index of symbols that many editors can use to quickly navigate the source code. Though many Unices ship with a version installed at /usr/bin/ctags, test_env.bash presumes that Exuberant Ctags is installed.

Vim Integration

Add this to your .vimrc to take advantage of Ctags integration in vim (where $TAGS_FILE is defined in test/test_env.bash):

" The tags path, as set below, will search the local file first, then the       
" project-wide file.
if $TAGS_FILE != ""                                                             
  if filereadable($TAGS_FILE)
    set tags+=$TAGS_FILE
  else                                                                          
    echo "Can't read $TAGS_FILE; tags not set"
  endif
endif

git-new-workdir

Usually installed as /usr/local/share/git-core/contrib/workdir/git-new-workdir, this will create a new working directory for a specified branch that's linked to the original repository. This is nice when working on multiple branches in parallel, as it doesn't require committing or stashing changes before issuing a git checkout to switch between branches. The following bash function wraps git-new-workdir to create a working dir called reponame-branchname in the same directory as the original repository:

# Creates a branch-specific git working directory in the same directory as the
# original repository.
git-new-workdir() {                                                             
  if test $# -ne 2; then
    echo "Usage: $FUNCNAME <git repo> <branch name>"                            
    return 1
  elif test ! -d $1; then
    echo "$1 does not exist"
    return 1
  fi
  new_workdir=$1-$2
  if /usr/local/share/git-core/contrib/workdir/git-new-workdir\
    $1 $new_workdir $2; then
    echo "Created $new_workdir"
  else
    return 1
  fi
}

tmux Terminal Multiplexer

The tmux terminal multiplexer is helpful for using a single terminal window to efficiently manage different editing and build sessions, amongst many other useful functions. tmux: Productive Mouse-Free Development from The Pragmatic Bookshelf is a great primer.

These are some helpful config options to add to ~/.tmux.conf, including getting GNU screen-like CTRL-a behavior:

set-option -g prefix C-a
unbind-key C-b
bind-key C-a send-prefix

bind R source-file ~/.tmux.conf \; display "Reloaded ~/.tmux.conf"
set -g default-terminal "screen-256color"
set -g status-style fg=black,bg=colour7
setw -g window-status-style fg=default,bg=default,none
setw -g window-status-current-style fg=black,bg=colour15,bold
set -g pane-active-border-style fg=default,bg=colour7
set -g message-style fg=black,bg=colour11,bright
set -g status-utf8 on
setw -g monitor-activity on
set -g visual-activity on

bind -r H resize-pane -L 5
bind -r J resize-pane -D 5
bind -r K resize-pane -U 5                                                      
bind -r L resize-pane -R 5

# Enables nohup to work. From:
# https://github.com/ChrisJohnsen/tmux-MacOSX-pasteboard                        
set-option -g default-command "reattach-to-user-namespace -l $SHELL"