OpenFOAM-extend on SourceForge.net Bernhard F.W. Gschaider 1 Martin Beaudoin 2 1 ICE Strömungsforschung Leoben, Austria 2 Institut de recherche d Hydro-Québec Varennes, Canada 4th OpenFOAM-Workshop 1st-4th June bgschaid, mbeaudoin OpenFOAM-extend 1/44
Outline 1 Introduction/History How it started SourceForge.net Subversion The OpenFOAM-extend project 2 What is there Usage/Community Contacts 3 4 Future development Points for discussion bgschaid, mbeaudoin OpenFOAM-extend 2/44
How it started SourceForge.net Subversion The OpenFOAM-extend project Before OpenFOAM-extend - circa 2006 Context: New OpenFOAM versions are released about once a year OpenFOAM patches and bugfixes are distributed through a discussion Forum Hrv s development version is available only through large tarballs from Zagreb FSB ftp server Keeping your OpenFOAM version up-to-date is a bit painful... First OpenFOAM Workshop in Zagreb in January 2006: Some of the many interesting ideas put forward: How about a public source code repository for OpenFOAM? OpenFOAM Workshops are more fun at sub-zero temperatures... bgschaid, mbeaudoin OpenFOAM-extend 3/44
How it started SourceForge.net Subversion The OpenFOAM-extend project Getting people involved - December 2006 Henry Weller was contacted to check OpenCFD s interest in a public source code repository for OpenFOAM No resources available to participate Needed sponsoring to get involved, even for in-kind contributions Doing it the Open Source way: People started to get involved Hrovje Jasak, Håkan Nilsson Bernhard Gschaider, Martin Beaudoin The main objective: Introduce a collaborative tool that would benefit a growing community The result: The OpenFOAM-extend project : http://openfoam-extend.sourceforge.net bgschaid, mbeaudoin OpenFOAM-extend 4/44
Why SourceForge.net? How it started SourceForge.net Subversion The OpenFOAM-extend project The world s largest open source software development web site Over 230,000 software projects registered Over 2,000,000 registered users Everything you need to start and grow an Open Source project Revision control systems (Subversion, CVS, Git, etc) Project Web site, Wiki Mailing lists, Forums Bug tracking tools Many hosted applications bgschaid, mbeaudoin OpenFOAM-extend 5/44
Why Subversion? Introduction/History How it started SourceForge.net Subversion The OpenFOAM-extend project Subversion: A stable and mature revision control system User interface available for many platforms A fairly large user base Subversion repository available for SourceForge.net projects Easy to download/maintain svn repository subtrees Why don t you switch to Git? SourceForge.net now offers Git repository Git downloads are impressively fast Git can t do partial checkout (subdirectory) If it ain t broke, don t fix it... bgschaid, mbeaudoin OpenFOAM-extend 6/44
How it started SourceForge.net Subversion The OpenFOAM-extend project The OpenFOAM-extend project - The mission The goal of this project is to open the OpenFOAM CFD toolbox to community contributed extensions, in the spirit of the Open Source development model. bgschaid, mbeaudoin OpenFOAM-extend 7/44
What is there Usage/Community Contacts In the SVN The major parts of the svn are: The Breeder Collection of assorted utilities and other contributions. Amongst others: The Turbomachinery Sig stuff funkysetfields, simplefunctionobjects and groovybc... and others. But not as many as we hoped for The Core or dev-version Hrv s development version The patch branch Collection of bug-fixes. Retired because the Git made it obsolete (which is a good thing) bgschaid, mbeaudoin OpenFOAM-extend 8/44
What is there Usage/Community Contacts Mailing-lists openfoam-extend-general A list for discussions about the OpenFOAM-extend-project, not OpenFOAM TM itself openfoam-extend-announce Announcements of new software openfoam-extend-submit This mailing-list receives a mail every time something is submitted to the Svn Special topic lists Public (for instance for the Ship Hydrodynamics SIG Teaching SIG Turbomachinery SIG Turbulence SIG ) or closed (for the workshop-organizers) lists bgschaid, mbeaudoin OpenFOAM-extend 9/44
Introduction/History What is there Usage/Community Contacts A contribution by the Teaching SIG OpenFOAM SLAX A fully configured binary OpenFOAM-1.5-dev platform based on a live Linux distro called SLAX a modern, portable, small and fast Linux operating system can run from from CD/DVD, USB Flash Key, Hard Drive, etc. Available at the Download section of OpenFOAM-extend Available on your Montreal Workshop USB stick bgschaid, mbeaudoin OpenFOAM-extend 10/44
Notification of updates What is there Usage/Community Contacts There are three ways to get notifications of updates in the Svn 1 The mailing-list 2 A Irc-channel 3 A Rss-feed More details can be found in the presentation The OpenFOAM-extend project on SourceForge: current status from the last workshop in Milano bgschaid, mbeaudoin OpenFOAM-extend 11/44
What is there Usage/Community Contacts What is not there. And why. Bugtracker Under discussion. Could be worth a test drive. Other binary distributions Would need someone willing to maintain them Forum software Don t want to create a parallel structure to the official forum Documentation The Wiki is the place for this Bugfixes: OpenFOAM-1.5.x The Git repository is the place for this 24/7 support Because we all have a day job... bgschaid, mbeaudoin OpenFOAM-extend 12/44
Usage statistics Introduction/History What is there Usage/Community Contacts Usage of the Svn as reported by SourceForge.net bgschaid, mbeaudoin OpenFOAM-extend 13/44
Who contributed Introduction/History What is there Usage/Community Contacts Contribution percentage (metric: number of commits) for the whole OpenFOAM-extend Subversion repository From May 2008 to May 2009 More than 10 different contributers so far, directly or indirectly The objective for 2010: pushing Hrv s contribution below 50%! bgschaid, mbeaudoin OpenFOAM-extend 14/44
Who is in charge What is there Usage/Community Contacts Currently the administrators for the project are (in alphabetical order) Martin Beaudoin Bernhard Gschaider Hrovje Jasak Håkan Nilsson bgschaid, mbeaudoin OpenFOAM-extend 15/44
What is there Usage/Community Contacts How to get write access to the Svn 1 Get a SourceForge.net-account 2 Contact one of the project-admins with this information: Your SourceForge.net-account-name Your real-life identity A description what you need the write access for ( Contribute bugfix to project XY, Add a new utility...) A description of your previous work/experience in OpenFOAM TM if we don t know you in person bgschaid, mbeaudoin OpenFOAM-extend 16/44
Disclaimer Introduction/History Theorem: No two people are alike Lemma: No two users are alike We ll try to describe some typical cases anyway bgschaid, mbeaudoin OpenFOAM-extend 17/44
Introduction/History Wants to use some utility, etc from OpenFOAM-extend Doesn t want to program An admirable trait. 1 1 We all hope to reach that level some day bgschaid, mbeaudoin OpenFOAM-extend 18/44
Basic Workflow Introduction/History 1 Locate it in the repository 2 Get it Directly via Svn As a tarball 3 Compile it According to chapter 3.2 of the OpenFOAM TM user-guide Using wmake, or by following the provided documentation bgschaid, mbeaudoin OpenFOAM-extend 19/44
Svn for non-developers With SVN you are always in a client/server situation Client your machine. The data there is called local copy Server the repository (in our case SourceForge.net) Software is defined by a unique location on the server Can be found by Browsing from the base URL with Web browser: http://openfoam-extend.svn.sourceforge.net/svnroot/openfoam-extend Copying from the announcement (on the Forum, the Wiki, your local newspaper) The location of the local copy does not matter The most common program for using Svn is a command-line tool called (surprise!) svn The actual action is signified by the second word (checkout, update...) Guis exist, but are to complicated for read-only users bgschaid, mbeaudoin OpenFOAM-extend 20/44
Getting software via SVN Getting the notorious funkysetfields 1 > cd THE_DIRECTORY_WHERE_I_STORE_MY_APPS > svn checkout https :// openfoam - extend.svn. sourceforge.net / svnroot /openfoam - extend / trunk / Breeder_1.5/ utilities / postprocessing / FunkySetFields 3 A FunkySetFields / funkysetfields A FunkySetFields / funkysetfields / funkysetfields.c 5 A FunkySetFields / funkysetfields / GeneratedFiles... 7 A FunkySetFields / examples / setlowerhalfandatube. funkysetfieldsdict U FunkySetFields 9 Checked out revision 1234. > cd FunkySetFields / 11 > wmake A bug fix was promised and we want to get it 1 > cd THE_DIRECTORY_WHERE_I_STORE_MY_APPS / FunkySetFields / > svn update 3 U FunkySetFields / funkysetfields / funkysetfields.c Updated to revision 1235 5 > wmake bgschaid, mbeaudoin OpenFOAM-extend 21/44
Tarballs Introduction/History If you can t use svn because Your SysAdmin won t install it Your boss looked up the definition of Subversion in Merriam-Webster Your doctor said you re using too many command-line tools already The whole SVN-repository can be browsed using the Url http://openfoam-extend.svn.sourceforge.net/viewvc/openfoam-extend/ If you found the directory you want press the Download GNU tarball-link at the bottom The whole contents will be downloaded as a complete archive Extract and compile where you see fit Disadvantage: updates of software are not as easy as with svn (copy directories around...) bgschaid, mbeaudoin OpenFOAM-extend 22/44
Downloading a tarball bgschaid, mbeaudoin OpenFOAM-extend 23/44
His motivation 1 Is using some OpenFOAM utility 2 Found a bug in it (Strange things happen ;) ) 3 Knows how to fix it 4 Wants to share the fix with the world Report bug to the developer Commit it directly to the Svn bgschaid, mbeaudoin OpenFOAM-extend 24/44
Reporting the patch If you 1 found a bug 2 don t want to use svn this is the way to go Procedure: 1 Find out who is in charge 2 Prepare all the stuff that is necessary 1 Description of the problem (maybe with a testcase) 2 Necessary changes (either the whole source-files or diffs/patches) 3 Send it to the maintainer bgschaid, mbeaudoin OpenFOAM-extend 25/44
Generating a patch This is quite easy if your sources are in a SVN local copy Finding out what you changed 1 > cd THE_DIRECTORY_WHERE_I_STORE_MY_APPS / FunkySetFields / > svn diff 3 Index : funkysetfields / funkysetfields.c =================================================================== 5 --- funkysetfields / funkysetfields.c ( revision 1234) +++ funkysetfields / funkysetfields.c ( working copy ) 7 @@ -212,7 +212,7 @@ if (! args. options (). found (" time ") &&! args. options (). found (" latesttime ")) { 9 FatalErrorIn (" main ()") << args. executable () 11 - << ": time / latesttime option is required " << endl + << ": time or latesttime option is required " << endl 13 << exit ( FatalError ); } Preparing the actual patch to send > svn diff > ThisIsWrongBernhard. patch bgschaid, mbeaudoin OpenFOAM-extend 26/44
Commiting to the Svn Preliminaries: 1 You have write access (technical level) 2 You checked with the maintainer (social level) 3 You re sure that you re only commiting what you want to (embarrassment level) Make sure that you read some basic tutorial on Svn before Doesn t have to be a book bgschaid, mbeaudoin OpenFOAM-extend 27/44
A commit to the Svn Checking the changes and commiting them 1 > cd THE_DIRECTORY_WHERE_I_STORE_MY_APPS / FunkySetFields / > svn status 3 M funkysetfields / funkysetfields.c > svn diff funkysetfields / funkysetfields.c 5 Index : funkysetfields / funkysetfields.c =================================================================== 7 --- funkysetfields / funkysetfields.c ( revision 1234) +++ funkysetfields / funkysetfields.c ( working copy ) 9 @@ -212,7 +212,7 @@ if (! args. options (). found (" time ") &&! args. options (). found (" latesttime ")) { 11 FatalErrorIn (" main ()") << args. executable () 13 - << ": time / latesttime option is required " << endl + << ": time or latesttime option is required " << endl 15 << exit ( FatalError ); } 17 > svn commit -m " This is the promised fix " Sending funkysetfields / funkysetfields.c 19 Transmitting file data... Committed revision 1235. bgschaid, mbeaudoin OpenFOAM-extend 28/44
Your contribution will be noticed The main developer will add your name to the README file of that utility if the contribution is large enough Fixing a typo in an error message is not Fixing a missing scaling factor of 1 probably is 2 Your name will appear in the svn log message bgschaid, mbeaudoin OpenFOAM-extend 29/44
Wrote a new utility and woke up one day thinking I think this can improve the lives of others (or maybe even prevent global warming). I think I want to share it Is willing to face the public opinion... and improve the code... fix bugs... write at least a little bit of documentation bgschaid, mbeaudoin OpenFOAM-extend 30/44
It s not only the code that is important NB: This slide is not here to discourage you, it is here to save us all some trouble Think about whether you want to share the stuff Consider the implications of the GNU Public License Check with your employer whether it is OK to share the stuff The exact implications may differ according to your country (legal system), your contract, etc but it boils down to: If someone paid you while doing it, then that someone has some say about it bgschaid, mbeaudoin OpenFOAM-extend 31/44
The GPL in 1 minute 23 seconds The GPL is all about distribution of software If you are modifying software that was distributed under the Gpl (GNU Public License) this software is also under the Gpl OpenFOAM TM is published under the Gpl Consequently on openfoam-extend you should only publish software under the Gpl You don t have to publish your work if it is based on Gpl-software... but you ll have to make the source available to whoever you are distributing it to (no binary-only distribution) bgschaid, mbeaudoin OpenFOAM-extend 32/44
How to upload it Introduction/History Get write access (you probably already got it) Locate the proper place in the repository If in doubt: ask Add and commit your stuff to the repository Make sure that nothing unwanted is there Write a meaningful commit-message Write documentation (at least a README) bgschaid, mbeaudoin OpenFOAM-extend 33/44
Definition of unwanted stuff Rule of thumb: Everything that was not generated by human intervention (with a text editor) Examples: Everything in Make/linux64GccOpt (or whatever your platform is) The.dep-files Backup-files from your text-editor (*~ for the Emacsists) For example-cases: Everything in constant/polymesh except for blockmeshdict All time-steps except the first bgschaid, mbeaudoin OpenFOAM-extend 34/44
Adding a new utility The ultimate utility > cd MY_SF_WORKING_COPY / utilities / preprocessing 2 > cp -r ~/ MY_PERSONAL_DEV_FOLDER / setsensibleboundaryconditions. > wclean setsensibleboundaryconditions ; rm~all 4 > svn add setsensibleboundaryconditions A setsensibleboundaryconditions 6 A setsensibleboundaryconditions / setbc.c A setsensibleboundaryconditions / notusedanymore.h 8 A setsensibleboundaryconditions / Make A setsensibleboundaryconditions /Make / files 10 A setsensibleboundaryconditions /Make / options > svn revert setsensibleboundaryconditions / notusedanymore.h 12 > svn commit -m "No more excuses for wrong boundary conditions " setsensibleboundarycondi Adding setsensibleboundaryconditions 14 Adding setsensibleboundaryconditions / setbc.c Adding setsensibleboundaryconditions / Make 16 Adding setsensibleboundaryconditions /Make / files Adding setsensibleboundaryconditions /Make / options 18 Transmitting file data... Committed revision 1236. Next project: A cure for the common cold bgschaid, mbeaudoin OpenFOAM-extend 35/44
What is expected of a developer Make the code readable Conforming to the OpenFOAM-conventions (Personal note: I didn t like them in the beginning, too) Provide documentation A README-file Documentation on the Wiki Maintain it bgschaid, mbeaudoin OpenFOAM-extend 36/44
The joint project Introduction/History Several people want to collaborate on some project from different organizations/countries Want to be sure that everyone of them always has access to the latest version Want to be able to backtrack changes Who inserted THAT change? Have no problem that other people watch their work progressing Examples: The stuff from the Turbomachinery SIG The alternatechemistry-library The simplefunctionobjects-library bgschaid, mbeaudoin OpenFOAM-extend 37/44
Growing up in public Basically the same rules as for the utility developer apply Be aware that other people might use your stuff - try to keep it in a usable state Try to submit an approximately working version with your first commit Coordinate yourself, so that you don t break each others changes If major changes are planned: do them in a branch bgschaid, mbeaudoin OpenFOAM-extend 38/44
Rules for contributing to the dev Once you are ready to contribute there, you will know them. We recommend you read through the instructions we have written in the Wiki at OpenFOAM-extend, as well as the README files that can be found in the svn. Basically: Learn to use svn correctly, if you don t know it already Stick to the Breeder. We have actually not come far enough ourselves to go to the Forge. Give some time to think about the structure of your directories and files. Ask if unsure. Clean up before committing, and commit no binary files Don t commit to directories that other people are working on unless you have a permission to do so. Discuss with us before committing anything else than your specific developments. bgschaid, mbeaudoin OpenFOAM-extend 39/44
Future development Points for discussion Future development - Test loops Compilation test-loops Nigthly Builds Continuous Builds Experimental Builds Execution test-loops OpenFOAM tutorials SIGs test cases Based on free software Kitware CMake, CTest, CDash Will be available on openfoam-extend CMake/CTest scripts With a public CDash Web service bgschaid, mbeaudoin OpenFOAM-extend 40/44
Future development Points for discussion What we want from you Contribute your bug fixes Share and document your test cases Share your test loops results Contribute your source code Contribute documentation and Howtos Keep on helping on the Forum Register to SIGs mailing lists Participate in SIGs All contributions are valuable!!!! bgschaid, mbeaudoin OpenFOAM-extend 41/44
Future development Points for discussion Compatibility to the upstream version Hrv is taking great care of syncing his dev version when a major version release of OpenFOAM is published. Keeping upstream compatibility is a key factor of OpenFOAM 1.5-dev Still, downstream compatibility is sometimes a problem when developing for both versions Some header files are different between 1.5-dev and 1.5.x 1.5-dev: repatch.h 1.5.x: repatchpolytopochanger.h Some classes are only present in 1.5-dev See Hrv s presentation for an overview of the numerous enhancements offered by OpenFOAM-1.5-dev Some useful features are only present in 1.5-dev Tolerance switches in the main controldict bgschaid, mbeaudoin OpenFOAM-extend 42/44
Future development Points for discussion The FOAM DEV environment variable to the rescue From simplefunctionobjects/make/options 1 ifdef FOAM_DEV FOAM_DEV_OPTION = - DFOAM_DEV 3 endif 5 EXE_INC = \ $( FOAM_DEV_OPTION ) \ 7 -I$( LIB_SRC )/ finitevolume / lninclude \ -I$( LIB_SRC )/ meshtools / lninclude \ 9 -I$( LIB_SRC )/ sampling / lninclude \ -I$( LIB_SRC )/ trisurface / lninclude \ 11 -I$( LIB_SRC )/ lagrangian / basic / lninclude 13 LIB_LIBS = \ 15 - lfinitevolume \ - lmeshtools \ 17 - lsampling \ - ltrisurface \ 19 - llagrangian bgschaid, mbeaudoin OpenFOAM-extend 43/44
Future development Points for discussion Conclusion Thanks for: your attention your feedback your (future) contributions bgschaid, mbeaudoin OpenFOAM-extend 44/44