Difference between revisions of "Testing and Development Tools and Tips"

From OpenSSLWiki
Jump to navigationJump to search
(Flesh out Ctags section)
(→‎test/testutil.h: Add ADD_TEST() and run_tests())
 
(10 intermediate revisions by the same user not shown)
Line 2: Line 2:
  
 
== Testing Environment and Tools ==
 
== Testing Environment and Tools ==
In [https://github.com/mbland/openssl/compare/test-util 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.
+
In [https://github.com/mbland/openssl/compare/test-util 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 <code>SETUP_TEST_FIXTURE</code> and <code>EXECUTE_TEST</code> macros. Should be pulled into the mainline pending acceptance of [https://github.com/openssl/openssl/pull/126 pull request #126].
+
[http://git.openssl.org/gitweb/?p=openssl.git;a=blob;f=test/testutil.h test/testutil.h] defines:
 +
* the generic <code>SETUP_TEST_FIXTURE</code> and <code>EXECUTE_TEST</code> macros; the header comments describe how to define test-specific macros based on these
 +
* <code>ADD_TEST()</code> and <code>run_tests()</code> to standardize the registration and execution of test case functions within <code>main()</code>
  
 
=== test/new-test.sh ===
 
=== test/new-test.sh ===
Generates a new automated test stub, following [http://mike-bland.com/2014/06/05/pseudo-xunit-pattern.html the Pseudo-xUnit Pattern] and using the macros from <code>test/testutil.h</code>. The generated stub will compile standalone.
+
[https://github.com/mbland/openssl/blob/test-util/test/new-test.sh test/new-test.sh (mbland's fork)] generates a new automated test stub, following [http://mike-bland.com/2014/06/05/pseudo-xunit-pattern.html the Pseudo-xUnit Pattern] and using the macros from <code>test/testutil.h</code>. The generated stub will compile standalone.
  
 
=== test/test_env.bash ===
 
=== 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.
+
[https://github.com/mbland/openssl/blob/test-util/test/test_env.bash test/test_env.bash (mbland's fork)]: contains 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 ==
Line 17: Line 19:
  
 
=== Vim Integration ===
 
=== Vim Integration ===
Once <code>$CSCOPE_DB</code> (defined in <code>test/test_env.bash</code> is built using <code>make-cscope</code>, you can take advantage of the Cscope integration in Vim by adding something like the following to your <code>.vimrc</code>:
+
Once <code>$CSCOPE_DB</code> (defined in <code>test/test_env.bash</code>) is built using <code>make-cscope</code>, you can take advantage of the Cscope integration in Vim by adding something like the following to your <code>.vimrc</code>:
  
 
<pre>
 
<pre>
Line 42: Line 44:
  
 
=== Vim Integration ===
 
=== Vim Integration ===
Add this to your <code>.vimrc</code> to take advantage of Ctags integration in vim:
+
Add this to your <code>.vimrc</code> to take advantage of Ctags integration in vim (where <code>$TAGS_FILE</code> is defined in <code>test/test_env.bash</code>):
  
 
<pre>
 
<pre>
Line 57: Line 59:
  
 
== git-new-workdir ==
 
== git-new-workdir ==
 +
Usually installed as <code>/usr/local/share/git-core/contrib/workdir/git-new-workdir</code>, 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 <code>git checkout</code> to switch between branches. The following <code>bash</code> function wraps <code>git-new-workdir</code> to create a working dir called <code>reponame-branchname</code> in the same directory as the original repository:
 +
 +
<pre>
 +
# 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
 +
}
 +
</pre>
 +
 +
'''Note:''' On Ubuntu 14.04, <code>git-new-workdir</code> is installed as part of the <code>git</code> package as <code>/usr/share/doc/git/contrib/workdir/git-new-workdir</code> and does not have execute permission by default.
 +
 +
== tmux Terminal Multiplexer ==
 +
[http://tmux.sourceforge.net/ 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. [http://pragprog.com/book/bhtmux/tmux tmux: Productive Mouse-Free Development] from The Pragmatic Bookshelf is a great primer.
 +
 +
These are some helpful config options to add to <code>~/.tmux.conf</code>, including getting GNU screen-like CTRL-a behavior:
 +
 +
<pre>
 +
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"
 +
</pre>

Latest revision as of 23:49, 19 July 2014

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[edit]

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[edit]

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
  • ADD_TEST() and run_tests() to standardize the registration and execution of test case functions within main()

test/new-test.sh[edit]

test/new-test.sh (mbland's fork) 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[edit]

test/test_env.bash (mbland's fork): contains 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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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
}

Note: On Ubuntu 14.04, git-new-workdir is installed as part of the git package as /usr/share/doc/git/contrib/workdir/git-new-workdir and does not have execute permission by default.

tmux Terminal Multiplexer[edit]

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"