README-NEW_PACKAGE

# ************************************************************************
# 
#                     New_Package Example Package
#                 Copyright (2004) Sandia Corporation
# 
# Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
# license for use of this work by or on behalf of the U.S. Government.
# 
# This library is free software; you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as
# published by the Free Software Foundation; either version 2.1 of the
# License, or (at your option) any later version.
#  
# This library is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.
#  
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
# USA
# Questions? Contact Michael A. Heroux (maherou@sandia.gov) 
# 
# ************************************************************************

********************************************************************
**************************** NOTICE ********************************
********************************************************************
*
* This New Package method is no longer supported. Please see the
* following Wiki page for adding a new package:
* https://github.com/trilinos/Trilinos/wiki/Adding-a-New-Package
*
********************************************************************

Useful Terminology:
	new package - A package to be added to the Trilinos Autotools
			configure/build process.

	new_package - The directory structure that this README file resides in.
			new_package serves as a guide for adding new packages
			to the Trilinos Autotools configure/build process.

	np - The generic name for a new package that is used 
			throughout this README.  The source code for np will be
			located in Trilinos/packages/np.  

	autotool'ed - A package that has been autotool'ed can use autotools
			for configuring and building.

BUGS
====

make distclean may not work
the test directory has not been autotool'ed


CONTENTS of new_package
=======================

new_package contains both static and dynamic examples of what should
be included in a new package.  The src and example directories are
dynamic examples - they can be bootstrapped, configured, compiled and
run.  They also demonstrate the use of two switches: 1) --enable-mpi,
a switch which most packages should support and 2)
--enable-newp_swahili, a switch used only with new_pacakge.  The test
directory is a static example.  It demonstrates what a complete
package should include, but has not yet been autotool'ed.  

The Trilinos/packages/new_package package was created as a tool for developers
wishing to utilize the Autotools configure/build process for a new or existing
Trilinos package.  Before beginning this process, approval must be obtained 
from the Trilinos Project Leader.

ADDING A NEW PACKAGE
====================

There are five general steps that need to be followed to add a new package to
the Trilinos Autotools configure/build process.  Note that these steps do not
have to be completed in the exact order listed below, nor does a step 
necessarily have to be completed in its entirety before moving onto the next
step.  (For example, a portion of a library can be autotool'ed and tested
before work begins on the rest of the library.)  The five steps are listed
below.

1. Write the non-generated files necessary for Autoconf and Automake.

Examples of all of the new, non-generated Autoconf and Automake files
required to add a packages to the Trilinos Autotools configure/build process 
are located within the new_package directory structure.  Most of these files
will need to be customized for each new package.  See the individual example 
files for more details.  Instructions for customizing are listed behind 
'#np#' in the following files:
     Trilinos/configure.ac
     Trilinos/packages/Makefile.am
     Trilinos/packages/new_package/Makefile.am
     Trilinos/packages/new_package/configure.ac  
     Trilinos/packages/new_package/src/Makefile.am
     Trilinos/packages/new_package/example/Makefile.am
     Trilinos/packages/new_package/example/example1/Makefile.am
     Trilinos/packages/new_package/test/Makfile.am
     Trilinos/packages/new_package/test/test1/Makefile.am
     Trilinos/packages/new_package/test/Hello_Test/Makefile.am
     Trilinos/packages/new_package/Makefile.export.new_package.in

The 'Hello_Test' Makefile.am uses Makefile.export, which is the recommended
way to build tests and examples.  The 'example1' and 'test1' Makefile.am's
do not use Makefile.export.  This should only be considered for packages that
don't use Makefile.export.  Using Makefile.export is highly recommended.

Note that not all of these files are used in building new_package, as it is 
a very simple package.

The following instructions may save you some time in this process:
(Make sure the environment variable TRILINOS_HOME is set to the top level
Trilinos directory of the Trilinos sandbox you are using.
Ex. 'setenv TRILINOS_HOME /home/user/Trilinos'.)

cd $TRILINOS_HOME/packages
cp -r new_package Yourpackagename

export PATH=$PATH:$TRILINOS_HOME/commonTools/refactoring
cd Yourpackagename
edit ConvertToYourpackagename-string-replace.list
edit ConvertToYourpackagename.sh
(Edit ConvertToYourpackagename-string-replace.list to use your package name
instead of Yourpackagename, yourpackagename, etc.  Edit the mv commands
in ConvertToYourpackagename.sh by changing the filenames in the second half
of the commands to the names you prefer.
The source files for new_package will obviously not be used in your
new package, but making these changes can help ensure a successful name
conversion.)
sh ConvertToYourpackagename.sh
rm ../ConvertToYourpackagename-string-replace.list 
./bootstrap

You then need to check all occurences of #np# and modify them as appropriate, 
you might also double check all occurences of #auto np# - to check the 
results of the automatic string replacement.



2. Create generated Autoconf and Automake files.

IMPORTANT: Before starting this phase, please see 
Trilinos/config/AutotoolsVersionInfo, obtain the correct version of both 
Autoconf and Automake.

If you change Trilinos/configure.ac or Trilinos/packages/Makefile.am,
run bootstrap in the Trilinos directory.  If you change
Trilinos/packages/np/Makefile.am, Trilinos/packages/np/configure.ac,
Trilinos/packages/np/src/Makefile.am or 
Trilinos/packages/np/example/Makefile.am type bootstrap in the 
Trilinos/packages/np directory.

The bootstrap should complete without any errors or warnings.

3.  Test and debug Autoconf and Automake files

After you have run bootstrap, run configure in a clean BUILD directory.
Disabling all packages that you will not need is recommended to save time.

echo is one way to print out variables.  AC_CHECK_FILE can be used 
to check for the existence of a particular file or directory.  


Do not run configure in the source directory.  If you have done so,
you will have to clean up the source directory before you can run
configure in a separate build directoy.  If make distclean does not
work (at present it does not work consistently) you may have to start
from scratch, with a cvs checkout and adding your new source files. 

4.  Add all Autoconf and Automake files to the Trilinos CVS repository 

The bootstrap command will generate files necessary for the configure
and build processes.  Each of these files MUST be added to the
repository with a 'cvs add'.

For new_package, we added the following non-generated files to the 
CVS repository:
   cvs add example/Makefile.am
   cvs add bootstrap configure.ac Makefile.am
   cvs add src/Makefile.am

For new_package, we added the following files in the config directory:

   cvs add ac_cxx_bool.m4 ac_cxx_have_std.m4 ac_cxx_have_stl.m4
   cvs add ac_cxx_mutable.m4 ac_cxx_namespaces.m4 ac_cxx_new_for_scoping.m4
   cvs add ac_cxx_reinterpret_cast.m4 ac_cxx_std_ios_base_fmtflags.m4
   cvs add ac_cxx_std_sprintf.m4 ac_prompt_user.m4 ac_prompt_user_no_define.m4
   cvs add acx_blas.m4 acx_check_dos_filesys.m4 acx_lapack.m4
   cvs add acx_pthread.m4 tac_arg_check_mpi.m4 tac_arg_config_mpi.m4
   cvs add tac_arg_enable_compiler_options.m4 tac_arg_enable_feature.m4
   cvs add tac_arg_enable_option.m4 tac_arg_with_ar.m4 tac_arg_with_blaslib.m4
   cvs add tac_arg_with_compiler.m4 tac_arg_with_flags.m4 
   cvs add tac_arg_with_incdirs.m4 tac_arg_with_lapacklib.m4
   cvs add tac_arg_with_libdirs.m4 tac_arg_with_package.m4
   cvs add config.guess config.sub install-sh missing mkinstalldirs 
   cvs add depcomp strip_dup_incl_paths.pl strip_dup_libs.pl

For new_package, we added the following automake and autoconf generated
files to the CVS repository:
   cvs add example/Makefile.in src/Makefile.in src/New_Package_config.h.in
   cvs add Makefile.in configure aclocal.m4

Not all of these files will be necessary for all packages.

5. Perform tests and request new Mailman lists.

ADDING TESTS TO THE TEST HARNESS
================================

Please see 
http://software.sandia.gov/trilinos/developer/test_harness/test_definitions.html

For information about adding tests to the Trilinos test harness.

IMPROVING PORTABILITY
=====================

Make sure that New_Package_config.h is included in all your source
files, directly or indirectly - unless you don't need
New_Package_config.h (as you might not if you don't have any package
specific options, like newp_swahili).  Include New_Package_config.h
before Epetra_ConfigDefs.h, or PACKAGE will get redefined.  Many 
portability issues have already been dealt with by other packages.  
It can be beneficial to include (directly or indirectly) the 
ConfigDefs file from another package that the new package depends 
on (if any) in every source file in the new package.