software_smithy 1.1

data/lib/smithy_version.rb

@@ -0,0 +1,40 @@
+# Smithy is freely available under the terms of the BSD license given below. {{{
+#
+# Copyright (c) 2012. UT-BATTELLE, LLC. All rights reserved.
+#
+# Produced by the National Center for Computational Sciences at Oak Ridge
+# National Laboratory. Smithy is a based on SWTools, more information on SWTools
+# can be found at: http://www.olcf.ornl.gov/center-projects/swtools/
+#
+# This product includes software produced by UT-Battelle, LLC under Contract No.
+# DE-AC05-00OR22725 with the Department of Energy.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# - Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+#
+# - Redistributions in binary form must reproduce the above copyright notice, this
+#   list of conditions and the following disclaimer in the documentation and/or
+#   other materials provided with the distribution.
+#
+# - Neither the name of the UT-BATTELLE nor the names of its contributors may
+#   be used to endorse or promote products derived from this software without
+#   specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+# }}}
+
+module Smithy
+  VERSION = '1.1'
+end

data/man/man1/smithy.1

@@ -0,0 +1,262 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "SMITHY" "1" "November 2012" "" ""
+.
+.SH "NAME"
+\fBsmithy\fR \- build, test, and install software with ease\.
+.
+.SH "SYNOPSIS"
+\fBsmithy\fR \fBnew\fR APPLICATION/VERSION/BUILD
+.
+.br
+\fBsmithy\fR \fBedit\fR last
+.
+.br
+\fBsmithy\fR \fBbuild\fR last
+.
+.br
+.
+.SH "DESCRIPTION"
+\fBsmithy\fR will help you get software installed quickly and painlessly\. This tool follows all the same conventions as swtools\. That is, directory structures, support files, and scripts are all in the same locations\. Smithy\'s goal is to make using those conventions easier\.
+.
+.P
+This is still a work in progress\. If you have any questions, suggestions, or encounter any errors please send me an email: anthonyd@ornl\.gov
+.
+.SH "COMMANDS"
+For help on all options and commands run \fBsmithy help\fR
+.
+.SH "EXAMPLES"
+This section shows the typical work\-flow for adding a new software build\. Let\'s imagine we want to install petsc 3\.2 using the cray compiler\. We must create a place for the software build, build it, and create a module\.
+.
+.P
+Note: all commands, options, and arguments have tab\-completion when using bash or zsh
+.
+.SS "1\. Creating The Build"
+All software builds have the following name format: \fBAPPLICATION/VERSION/BUILD\fR That is three different parts separated by forward slashes \fB/\fR Each part consists of:
+.
+.TP
+\fBAPPLICATION\fR
+The name using lowercase characters
+.
+.TP
+\fBVERSION\fR
+Numbers with periods\. I recommend that whatever you choose as a version allows it to be lexigraphically sorted from oldest to newest\.
+.
+.TP
+\fBBUILD\fR
+Build is somewhat different, it consists of the intended operating system and compiler separated by underscores (\fB_\fR)\. It is important to use compiler version numbers that correspond to module versions\. This will allow smithy to auto\-generate modulefiles for software with multiple builds\. As an example:
+.
+.IP
+\fBsles11\.1_gnu4\.6\.2\fR corresponds to SuSE Linux Enterprise Server 11\.1 and the GNU gcc compiler 4\.6\.2
+.
+.IP
+\fBcle4\.0_pgi12\.1\.0\fR corresponds to Cray Linux Environment 4\.0 and the PGI 12\.1\.0 compile
+.
+.P
+Let\'s use \fBpetsc/3\.2/cle4\.0_cray8\.0\.1\fR as the name\. This would be petsc designed to run on a cle4\.0 compute node and compiled with the cray cce 8\.0\.1 compiler\. This can be accomplished by running:
+.
+.IP "" 4
+.
+.nf
+
+smithy new petsc/3\.2/cle4\.0_cray8\.0\.1
+.
+.fi
+.
+.IP "" 0
+.
+.P
+You can save yourself some extra time by telling smithy where the tar file for petsc is:
+.
+.IP "" 4
+.
+.nf
+
+smithy new \-t /sw/sources/petsc/3\.2/petsc\-lite\-3\.2\-p7\.tar\.gz petsc/3\.2/cle4\.0_cray8\.0\.1
+.
+.fi
+.
+.IP "" 0
+.
+.P
+When using the \fB\-t\fR, \fB\-\-tarfile=\fR option smithy will extract the given archive to the \fBsource\fR directory\. For the petsc example above this would be \fB/sw/xk6/petsc/3\.2/cle4\.0_cray8\.0\.1/source\fR
+.
+.P
+If this is a brand new piece of software add the \fB\-\-web\-description\fR switch\. This will create the application description files too\.
+.
+.SS "2\. Editing and Building the Software:"
+Once you have created the build you may need to update the build (\fBrebuild\fR) and environment (\fBremodule\fR) scripts before building the software\. Both files live within the software prefix\. For our example it is located in \fB/sw/xk6/petsc/3\.2/cle4\.0_cray8\.0\.1\fR\. You can edit this and other related files using the \fBedit\fR command:
+.
+.IP "" 4
+.
+.nf
+
+smithy edit build petsc/3\.2/cle4\.0_cray8\.0\.1
+.
+.fi
+.
+.IP "" 0
+.
+.P
+This is just a convenience command to editing the rebuild script\. It will expect the \fB$EDITOR\fR environment variable to be set to the edior of your choice\. You can alternatively use the \fB\-e\fR,\fB\-\-editor=\fR option\. To make things quicker you can run:
+.
+.IP "" 4
+.
+.nf
+
+smithy edit last
+.
+.fi
+.
+.IP "" 0
+.
+.P
+By omitting the build argument, smithy will prompt you to select the file to edit\. The \fBlast\fR argument will tell smithy to use the last software build it worked with\. If you are not sure what the last one is you can run \fBsmithy show last\fR to see\.
+.
+.P
+Once you have edited the files, it\'s time to build\. Do so by running:
+.
+.IP "" 4
+.
+.nf
+
+smithy build last
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The results of the run will be shown on the screen and simultaneously logged to \fBbuild\.log\fR withing the software prefix folder\.
+.
+.SS "3\. Create and edit a modulefile:"
+This step is best done after all builds for a particular application have been created\. When you create a new software build a modulefile is created too\. For our petsc install it lives in: \fB/sw/xk6/petsc/3\.2/modulefile\fR All builds of a particular application share a single modulefile\.
+.
+.P
+Smithy does some guessing as to what should be inside the modulefile based on what builds you have\. If there is only one build the modulefile is relatively simple\. If you have multiple builds for different compilers then it will be more complicated\.
+.
+.P
+To be sure the modulefile is up to date on each build, regenerate it with:
+.
+.IP "" 4
+.
+.nf
+
+smithy module create last
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Launch your editor with:
+.
+.IP "" 4
+.
+.nf
+
+smithy edit modulefile last
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Add any relevant variables to your application\. Next you will need to test it to make sure it is loading properly for each build and that there are no errors\. You can add the modulefile to your \fB$MODULEPATH\fR using:
+.
+.IP "" 4
+.
+.nf
+
+smithy module use last
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Now you are free to display and load it using the normal module commands:
+.
+.IP "" 4
+.
+.nf
+
+module avail      petsc
+module display    petsc/3\.2
+module load       petsc/3\.2
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Once the modulefile is ready, you can copy it into place using:
+.
+.IP "" 4
+.
+.nf
+
+smithy module deploy last
+.
+.fi
+.
+.IP "" 0
+.
+.P
+For out petsc example, this command will copy \fB/sw/xk6/petsc/3\.2/modulefile/petsc/3\.2\fR to \fB/sw/xk6/modulefiles/petsc/3\.2\fR
+.
+.SS "4\. Website Description"
+If this is a new application you will need to add some information to the description file\. For petsc this lives in: \fB/sw/xk6/petsc/description\fR This is an html formatted file\. Alternatively, it can live in \fB/sw/xk6/petsc/description\.markdown\fR this file is in markdown format and is a bit simpler to write than html\. See http://kramdown\.rubyforge\.org/quickref\.html for more information on markdown syntax\. If both files exist, the markdown file takes precedence\.
+.
+.P
+If the description file is missing you can generate one by running:
+.
+.IP "" 4
+.
+.nf
+
+smithy repair last
+.
+.fi
+.
+.IP "" 0
+.
+.P
+To publish to the website run:
+.
+.IP "" 4
+.
+.nf
+
+smithy publish petsc
+.
+.fi
+.
+.IP "" 0
+.
+.SH "LICENSE"
+Smithy is freely available under the terms of the BSD license given below\.
+.
+.P
+Copyright (c) 2012\. UT\-BATTELLE, LLC\. All rights reserved\.
+.
+.P
+Produced at the National Center for Computational Sciences in Oak Ridge National Laboratory\.
+.
+.P
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+.
+.IP "\(bu" 4
+Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer\.
+.
+.IP "\(bu" 4
+Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution\.
+.
+.IP "\(bu" 4
+Neither the name of the UT\-BATTELLE nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission\.
+.
+.IP "" 0
+.
+.P
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED\. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE\.

data/smithy.rdoc

@@ -0,0 +1,281 @@
+== smithy - Smithy will help you build, test, and install software with ease.
+
+v1.1
+
+=== Global Options
+=== --arch NAME
+
+Machine architecure to operate on
+
+[Default Value] None
+
+
+=== --config-file FILE
+
+Alternate config file, also set by $SMITHY_CONFIG
+
+[Default Value] None
+
+
+=== --descriptions-root PATH
+
+The root level directory global description files
+
+[Default Value] None
+
+
+=== --file-group-name GROUP
+
+Group name for files created by smithy
+
+[Default Value] None
+
+
+=== --prgenv-prefix NAME
+
+The prefix of programming environments for this machine
+
+[Default Value] None
+
+
+=== --software-root PATH
+
+The root level directory for software
+
+[Default Value] None
+
+
+=== --web-root PATH
+
+The root level directory for published web files
+
+[Default Value] None
+
+
+=== --[no-]colors
+Disable or enable color output (default: enabled)
+
+
+
+=== --disable-group-writable
+Disable group writable file creation
+
+
+
+=== -f|--force
+Always overwrite existing files
+
+
+
+=== --help
+Show this message
+
+
+
+=== --version
+
+
+
+
+=== Commands
+==== Command: <tt>build  PATH</tt>
+Build software
+
+The software to build may be either the absolute path or the full name of the software. The full name includes version numbers and build names using the format: NAME/VERSION/BUILD.
+===== Options
+===== --log-name FILE
+
+Build log file name located within the software prefix.
+
+[Default Value] build.log
+
+
+===== --disable-log
+Disable logging
+
+
+
+===== -f|--force
+Ignore .lock file and run anyway
+
+
+
+===== -n|--dry-run
+See what scripts will be run without running them
+
+
+
+===== -s|--suppress-stdout
+Suppress messages from STDOUT.
+
+
+
+==== Command: <tt>edit  build|test|env|modulefile NAME</tt>
+Edit package support files
+
+
+===== Options
+===== -e|--editor BINARY
+
+Editor for opening script files
+
+[Default Value] None
+
+
+===== -s|--split
+Split editing window with requested file and the environment (remodule) file
+
+
+
+==== Command: <tt>help  command</tt>
+Shows a list of commands or help for one command
+
+Gets help for the application or its commands. Can also list the commands in a way helpful to creating a bash-style completion function
+===== Options
+===== -c
+List commands one per line, to assist with shell completion
+
+
+
+==== Command: <tt>module  NAME</tt>
+Manage modulefiles for a package
+
+
+===== Options
+===== -n|--dry-run
+See what files will be created without creating them
+
+
+
+===== Commands
+====== Command: <tt>create </tt>
+Generate a modulefile for a given package. This operation normally happens after creating a new package. It is provided separately here for use with existing packages.
+
+
+====== Command: <tt>deploy </tt>
+Copy a package's modulefile to the system module path. This is typically done after you have tested a new module in isolation.
+
+
+====== Command: <tt>edit </tt>
+alias for 'smithy edit modulefile'
+
+
+====== Command: <tt>use </tt>
+Run the proper module command to add a package's modulefile to the MODULEPATH. This allows you to edit and test a modulefile in isolation. By adding the correct directory to MODULEPATH you may run module commands as you normally would.
+
+
+==== Command: <tt>new  NAME</tt>
+Generate a new build and all necessary files
+
+The new command will create all necessary files needed to add a new software package. Some care should be given to naming new packages. Some considerations are package names, version numbers, and build names. New package names should be of the format NAME/VERSION/BUILD
+
+- NAME of the package should be all lower case and one word. If multiple words are necessary separate them with dashes '-'.
+
+- VERSION numbers should be standard numbers separated by periods. If another format is necessary ensure that the numbers can be lexigraphically sorted in order of oldest release to newest.
+
+- BUILD names should consist of two pieces of information separated by an underscore '_', the package's intended operating system and compiler.
+
+EXAMPLES:
+
+silo/4.8/sles11.1_gnu4.5.3
+fftw/3.2.2/cle4.0_pgi11.10.0
+===== Options
+===== -t|--tarball FILE|URL
+
+Provide a tarball to unpack, either a file or URL (optional)
+
+[Default Value] None
+
+
+===== -n|--dry-run
+See what files will be created when running new without creating them
+
+
+
+===== --skip-modulefile
+Skip modulefile generation
+
+
+
+===== --web-description
+Create description file for website
+
+
+
+==== Command: <tt>publish  NAME</tt>
+Publish packages to web
+
+
+===== Options
+===== -n|--dry-run
+See what files will be created without creating them
+
+
+
+==== Command: <tt>repair  NAME</tt>
+Repair a package
+
+Repair permissions and check that files exist
+===== Options
+===== -n|--dry-run
+Verify permissions only
+
+
+
+==== Command: <tt>search  PATTERN</tt>
+Search currently installed software
+
+
+===== Options
+===== --format path|name|table|csv|dokuwiki
+
+Format of the output
+
+[Default Value] path
+
+
+==== Command: <tt>show </tt>
+Display internal smithy values
+
+
+===== Commands
+====== Command: <tt>arch </tt>
+List all architectures know to smithy.
+
+
+====== Command: <tt>last </tt>
+Display the package name used in the last smithy command. This is stored in the '~/.smithyrc' file.
+
+
+==== Command: <tt>test </tt>
+Test software
+
+
+===== Options
+===== --log-name FILE
+
+Test log file name located within the software prefix.
+
+[Default Value] test.log
+
+
+===== --disable-log
+Disable logging
+
+
+
+===== -f|--force
+Ignore .lock file and run anyway
+
+
+
+===== -n|--dry-run
+See what scripts will be run without running them
+
+
+
+===== -s|--suppress-stdout
+Suppress messages from STDOUT.
+
+
+