User Tools

Site Tools


build:fallbacks_contrib

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
build:fallbacks_contrib [2018/03/01 17:07]
Yann Pouillon [Hacking the fallbacks]
build:fallbacks_contrib [2018/03/01 17:20] (current)
Yann Pouillon
Line 13: Line 13:
 Unless you are an Abinit Developer, we will not provide any support regarding these topics, which are widely documented on many websites. [[https://​www.wikipedia.org/​|Wikipedia]] is a good starting point. Unless you are an Abinit Developer, we will not provide any support regarding these topics, which are widely documented on many websites. [[https://​www.wikipedia.org/​|Wikipedia]] is a good starting point.
  
-The best way to make the fallbacks evolve towards a direction useful to you is to [[http://​www.abinit.org/​about/​help-abinit|join the Abinit Project]] ​or the [[https://​launchpad.net/​~abinit-fallbacks-developers|Abinit Fallbacks Developers Team on Launchpad]]. If you have no Launchpad account yet, you will find useful instructions on the [[http://​esl.cecam.org/​mediawiki/​index.php/​Getting_started_with_Launchpad|CECAM ESL Wiki]] --- which most of us participate to as well --- on how to get started with Launchpad.+The best way to make the fallbacks evolve towards a direction useful to you is to [[http://​www.abinit.org/​about/​help-abinit|join the Abinit Project]].
  
 By joining the team, you commit to: By joining the team, you commit to:
   * take full care of all the data related to the packages you add to the list, including long-term maintenance;​   * take full care of all the data related to the packages you add to the list, including long-term maintenance;​
-  * provide support for all the packages you are responsible for and accept support ​request ​from the users of Abinit;+  * provide support for all the packages you are responsible for and accept support ​requests ​from the users of Abinit;
   * improve the visibility and availability of the packages you are responsible for, so that they can be used as fully independent packages instead of fallbacks;   * improve the visibility and availability of the packages you are responsible for, so that they can be used as fully independent packages instead of fallbacks;
   * participate to on-line and in-person meetings to globally improve the quality of Abinit and its surrounding ecosystem;   * participate to on-line and in-person meetings to globally improve the quality of Abinit and its surrounding ecosystem;
   * accept that orphan packages have to be removed to maintain the overall quality of the whole.   * accept that orphan packages have to be removed to maintain the overall quality of the whole.
 +
 +In exchange, you will receive help, training and collaboration from other Abinit Developers with all the issues you may encounter.
  
 Please note that if you do not join the team, you will have to maintain your modified versions of the fallbacks on your own, including synchronization with the trunk. Please note that if you do not join the team, you will have to maintain your modified versions of the fallbacks on your own, including synchronization with the trunk.
Line 29: Line 31:
   * be free software, [[https://​www.gnu.org/​philosophy/​free-sw.en.html|in the GNU sense]];   * be free software, [[https://​www.gnu.org/​philosophy/​free-sw.en.html|in the GNU sense]];
   * work stand-alone and be downloadable from its own webpage;   * work stand-alone and be downloadable from its own webpage;
-  * have an Autotools-based build system; +  * have an Autotools-based or Cmake-based build system; 
-  * have a test suite, unit tests being a priority;+  * have a test suite with sufficient coverage;
   * accept debug flags;   * accept debug flags;
   * be sufficiently documented to be installed and used by beginners;   * be sufficiently documented to be installed and used by beginners;
Line 36: Line 38:
   * be actually developed and maintained.   * be actually developed and maintained.
  
-In particular, **at no time may the Abinit Fallbacks be considered as a substitute for the distribution of undocumented and untested low-quality ​crappy ​code with support to be delegated to the Abinit Developers**. And since the Abinit Test Farm will be used for the validation of its portability,​ adopting a design strategy oriented towards portability and interoperability will greatly ease its integration with the already existing fallbacks.+In particular, **at no time may the Abinit Fallbacks be considered as a substitute for the distribution of undocumented and untested low-quality code with support to be delegated to the Abinit Developers**. And since the Abinit Test Farm will be used for the validation of its portability,​ adopting a design strategy oriented towards portability and interoperability will greatly ease the integration ​of your package ​with the already existing fallbacks.
  
-Another important aspect is that a package integrated within the Abinit Fallbacks must always remain available as a fully autonomous and stand-alone package at the same time. In other words, the Abinit Fallbacks cannot substitute the normal distribution of a package, even if it comes out of Abinit. Many mature and reliable services such as [[https://​gitlab.com/​|Gitlab]][[https://​github.com/​|GitHub]], and [[https://​launchpad.net/​|Launchpad]] make it extremely easy to distribute free software and provide much broader services than a //ad-hoc// simplified embedding system could ever do.+Another important aspect is that a package integrated within the Abinit Fallbacks must always remain available as a fully autonomous and stand-alone package at the same time. In other words, the Abinit Fallbacks cannot substitute the normal distribution of a package, even if it comes out of Abinit. Many mature and reliable services such as [[https://​gitlab.com/​|Gitlab]] ​and [[https://​github.com/​|GitHub]] make it extremely easy to distribute free software and provide much broader services than a //ad-hoc// simplified embedding system could ever do.
  
 Last but not least, the package must follow some conventions when installing files: Last but not least, the package must follow some conventions when installing files:
Line 44: Line 46:
   * be able to install executables in //​PREFIX/​bin//;​   * be able to install executables in //​PREFIX/​bin//;​
   * be able to install C headers and Fortran modules in //​PREFIX/​include//;​   * be able to install C headers and Fortran modules in //​PREFIX/​include//;​
-  * be able to install libraries in //​PREFIX/​lib//​.+  * be able to install libraries in //​PREFIX/​lib//​
 +  * allow for staged installs, i.e. //​$(DESTDIR)/​PREFIX//;​
 where //PREFIX// is the top install directory of the package. These conditions are usually fulfilled when using standard build systems. where //PREFIX// is the top install directory of the package. These conditions are usually fulfilled when using standard build systems.
  
 ===== Procedure ===== ===== Procedure =====
  
-There is a standard procedure to improve the Abinit Fallbacks. It involves different levels of validation and may take a significant amount of time before the new fallbacks are fully deployed. Please expect significant delays and be prepared to contribute with the Test Farm Team all along the process+There is a standard procedure to improve the Abinit Fallbacks. It involves different levels of validation and may take a significant amount of time before the new fallbacks are fully deployed. Please expect significant delays and be prepared to contribute with the Test Farm Team all along the process. Once a new package has been successfully installed, providing newer versions is relatively faster.
  
-<WRAP tip>​Please note that you have first to request ​access to the Abinit Fallbacks repository to the Test Farm Team before starting to contribute to the fallbacks.</​WRAP> ​+<WRAP tip>​Please note that you have first to request ​an Abinit Fallbacks repository ​access ​to the Test Farm Team before starting to contribute to the fallbacks.</​WRAP> ​
  
 Here are the different steps: Here are the different steps:
   - Clone the [[https://​gitlab.abinit.org/​buildbot/​abinit-fallbacks|Abinit Fallbacks repository]].   - Clone the [[https://​gitlab.abinit.org/​buildbot/​abinit-fallbacks|Abinit Fallbacks repository]].
-  - Implement the modifcations+  ​- [[https://​gitlab.abinit.org/​buildbot/​abinit-fallbacks/​issues|Submit an issue]] to describe your work and discuss it if necessary. 
-  - Run //​./​quicktest.sh//​ from the top source directory and fix the issues ​until it succeeds.+  - Create a new branch. 
 +  ​- Implement the desired modifications
 +  - Run //​./​quicktest.sh//​ from the top source directory and correct ​the errors ​until it succeeds.
   - Install the new fallbacks on your computer and test Abinit with them.   - Install the new fallbacks on your computer and test Abinit with them.
-  - Go back to step until step succeeds. +  - Go back to step until step succeeds. 
-  - Request ​deployment on the test farmspecifying the branch and its commit checksum+  - Submit ​merge request to the master branchin order to trigger additional tests
-  - Set your Abinit branch to use the new fallbacks and push it+  - Once merged, set your Abinit branch to use the new fallbacks and push it.
-  - Go back to step 2 until the builds and tests of Abinit succeed on the whole test farm. +
-  - Send a pull request to the fallbacks maintainers,​ specifying the branch and commit checksum to merge.+
  
 <WRAP important>​**IMPORTANT NOTE** \\ Please note that this full procedure has to be performed for any of the modifications described in the sections below.</​WRAP>​ <WRAP important>​**IMPORTANT NOTE** \\ Please note that this full procedure has to be performed for any of the modifications described in the sections below.</​WRAP>​
Line 81: Line 84:
  
 All these steps should of course be taken as early as possible, in order to make the changes as smooth as possible for everybody. Ideally, informing and coordinating should be done when starting the project or its next development cycle, with an early reminder as the release date approaches. All these steps should of course be taken as early as possible, in order to make the changes as smooth as possible for everybody. Ideally, informing and coordinating should be done when starting the project or its next development cycle, with an early reminder as the release date approaches.
 +
  
 ===== Enhancing the portability of a package ===== ===== Enhancing the portability of a package =====
Line 195: Line 199:
  
 If you wish to add a tricks macro for a new package, we recommend that you copy/paste the closest existing macro, automatically replace the package name in the new macro (both upper-case and lower-case),​ and modify the code to match the needs of the new package. Please place the new macro in the file following alphabetical order. If you wish to add a tricks macro for a new package, we recommend that you copy/paste the closest existing macro, automatically replace the package name in the new macro (both upper-case and lower-case),​ and modify the code to match the needs of the new package. Please place the new macro in the file following alphabetical order.
 +
  
 ===== Removing a package ===== ===== Removing a package =====
Line 208: Line 213:
  
 In principle, the extremely automated build system of the fallbacks should take care of updating all the relevant information when running //​./​quicktests.sh//​. If you encounter issues unrelated to the deleted package, please contact the fallbacks developers team as soon as possible. In principle, the extremely automated build system of the fallbacks should take care of updating all the relevant information when running //​./​quicktests.sh//​. If you encounter issues unrelated to the deleted package, please contact the fallbacks developers team as soon as possible.
 +
  
 ===== Adding a new package ===== ===== Adding a new package =====
Line 227: Line 233:
  
 Once you have provided the required enhancements,​ the extremely automated build system of the fallbacks should take care of the rest by itself when running //​./​quicktests.sh//​ from the top source directory. If you encounter issues unrelated with the new package, please contact the fallbacks maintainers as soon as possible. Once you have provided the required enhancements,​ the extremely automated build system of the fallbacks should take care of the rest by itself when running //​./​quicktests.sh//​ from the top source directory. If you encounter issues unrelated with the new package, please contact the fallbacks maintainers as soon as possible.
 +
  
 ===== Patching a package ===== ===== Patching a package =====
build/fallbacks_contrib.txt · Last modified: 2018/03/01 17:20 by Yann Pouillon