Changes between Version 4 and Version 5 of pm-svn-externals


Ignore:
Timestamp:
Oct 17, 2006 4:24:22 PM (14 years ago)
Author:
andreasw
Comment:

adapted to new policy

Legend:

Unmodified
Added
Removed
Modified
  • pm-svn-externals

    v4 v5  
    1 = Handling Svn Externals =
     1= Handling Subversion Externals =
    22
    3 Externals allow subversion to download additional packages from other subversion repositories.  For example, the COIN project {{{Clp}}} requires the COIN project {{{CoinUtils}}} to be compiled.  Therefore, the {{{Clp}}} repository has externals defined so that {{{CoinUtils}}} is automatically downloaded when a user checks out {{{Clp}}}.
     3'''Externals allow subversion to download additional packages from other subversion repositories.'''  For example, the COIN project {{{Clp}}} requires the COIN project {{{CoinUtils}}} to be compiled.  Therefore, the {{{Clp}}} repository has externals defined so that {{{CoinUtils}}} is automatically downloaded when a user checks out {{{Clp}}}.
    44
    55== Basics ==
    66
    7 Externals are defined as a property associated with a directory in a subversion repository (with the name {{{svn:externals}}}).  If someone checks out such a directory, the corresponding externals (defined as URLs) are also checked out, into subdirectores of that directory.  The names of those subdirectories, as well as the URL, are defined in the {{{svn:externals}}} property.  It is possible to specify a specific revision number for an external.  This helps us in COIN to make sure that people get a compatible version of the dependency; the latest {{{trunk}}} version of the dependency might not work with the code of the package one tries to download and compile, if the development of the dependency has proceeded.
     7Externals are defined as a [wiki:pm-svn-cmds#SubversionProperties subversion property] associated with a directory in a subversion repository (with the name {{{svn:externals}}}).  If someone checks out such a directory, the corresponding externals (defined as URLs) are also checked out, into subdirectores of that directory.  The names of those subdirectories, as well as the URL, are defined in the {{{svn:externals}}} property.  It is possible to specify a specific revision number for an external.  This helps us in COIN to make sure that people get a compatible version of the dependency; the latest development version in {{{trunk}}} of the dependency might not work with the code of the package one tries to download and compile, if the development of the dependency has proceeded.  Also, we can ensure in this way that point releases will also always obtain the same version of their dependencies.
    88
    99Externals are checked out recursively, ''i.e.'', if there is an {{{svn:externals}}} property defined in a directory downloaded for an external, it is also downloaded.  One can suppress the checkout (or the action of other {{{svn}}} commands) of externals by specifying the {{{--ignore-externals}}} flag.
     
    1111== Externals in COIN ==
    1212
    13 In COIN, we use externals mainly to make sure that COIN packages which require other COIN packages obtain the dependency code automatically.
     13'''In COIN, we use externals mainly to make sure that COIN packages which require other COIN packages obtain the dependency code automatically.'''
    1414
    15 Our policy for managing externals in COIN is that we put a file called {{{Externals}}} into the directory, from which the {{{svn:externals}}} property is set.  For example, the {{{Externals}}} file in the base directory for the {{{Clp}}} package might look like this:
     15'''Our policy for managing externals in COIN is that we put a file called {{{Externals}}} into the directory, from which the {{{svn:externals}}} property is set.'''  For example, the [https://projects.coin-or.org/Clp/browser/releases/1.3.3/Externals?format=raw Externals file in the base directory for the 1.3.3 point release of the Clp package] looks like this:
    1616
    1717{{{
    18 BuildTools         https://projects.coin-or.org/svn/BuildTools/trunk
    19 Data/Netlib        https://projects.coin-or.org/svn/Data/trunk/Netlib
    20 Data/Sample        https://projects.coin-or.org/svn/Data/trunk/Sample
    21 CoinUtils    -r500 https://projects.coin-or.org/svn/CoinUtils/trunk/CoinUtils
     18MSVisualStudio -r83  https://projects.coin-or.org/svn/MSVisualStudio/trunk/ExternalsDirs/Clp
     19BuildTools    https://projects.coin-or.org/svn/BuildTools/releases/0.5.1
     20Data/Netlib   https://projects.coin-or.org/svn/Data/releases/1.0.0/Netlib
     21Data/Sample   https://projects.coin-or.org/svn/Data/releases/1.0.0/Sample
     22CoinUtils     https://projects.coin-or.org/svn/CoinUtils/releases/1.0.0/CoinUtils
    2223}}}
    2324
    24 The first column specifies the directory (relative to the current directory) into which the external is to be placed (this can specify several levels of subdirectories).  After this, one can optionally specify the revision number of the dependency code that is to be obtained using the {{{-rN}}} flag, where {{{N}}} is the revision number.  The last column is the URL that specifies the repository for the dependency.
     25The first entry in each row specifies the directory (relative to the current directory) into which the external is to be placed (this can specify several levels of subdirectories).  After this, one can optionally specify the revision number of the dependency code that is to be obtained using the {{{-rN}}} flag, where {{{N}}} is the revision number.  The last column is the URL that specifies the repository for the dependency.
    2526
    26 == Changing Externals ==
     27== Important Considerations For Externals ==
     28
     29'''It is [wiki:pm-svn-releases mandatory] that the externals for a point release in a {{{releases/}}} subdirectory specify dependencies that do not change at any later point in time''', so that the original [wiki:pm-svn-releases#WorkingWithPointReleases point release] can always be recreated.  ''We have no mechanism in place that enforces this, so we reply on the projects manager's discipline to adhere to this convention.''
     30
     31In the above example we see that all external have been set to things are not going to change at some later point in time:  By [wiki:pm-svn-releases convention], subdirectories in the {{{releases/}}} directories for each COIN project are [wiki:pm-svn-branches tags], i.e., they should never be changed once they have been created, so pointing to specific subdirectories there is Ok.  If for some reason the required code is not available in a {{{releases/}}} subdirectory, the externals definition ''must'' specify a particular subversion repostiroy revision number using the {{{-r}}} flag, such as for the {{{MSVisualStudio}}} entry above.
     32
     33== Manipulating Externals ==
    2734
    2835To see the value of a property (such as {{{svn:externals}}}) one uses the {{{svn propget}}} command.  For example, to see the current value set for the externals in the {{{Clp}}} base directory, you go into the {{{Clp}}} base directory and issue the command
     
    5259
    5360More information about externals can be obtained in the [http://svnbook.red-bean.com/nightly/en/svn.advanced.externals.html Externals Definitions] chapter of the subversion book.
     61
     62== Preparing Externals For A Point Release ==
     63
     64Typically, a COIN project that depends on other COIN projects will point to a {{{stable}}} branch of the dependencies, so that one will always receive the latest improvements and bugfixes of the dependencies.  (By convention, the compilation should not break, since compatibility of the code should be ensure throughout a particular stable branch).
     65
     66If you now want to create a new point release from the latest version in your stable branch, we suggest you follow these steps:
     67
     68 1. Get a local copy of your stable branch (you probably have it already)
     69 1. For each dependency in your Externals file find the latest point release nuymber.  You can do this for example using
     70{{{
     71svn list https://projects.coin-or.org/svn/DepPrcjt/releases
     72}}}
     73 where {{{DepPrcjt}}} is the name of the dependency project.
     74 1. Change entries for all externals in the Externals file to point to the latest point releases.
     75 1. Update the actual subversion {{{svn:externals}}} property of the directory:
     76{{{
     77svn pset svn:externals -F Externals .
     78}}}
     79 1. Update the local copies in your working copy by typing {{{svn update}}}.  (Note:  If you have local changes in your checked-out externals, you should get those committed into the dependecy's repository first.  It is not a good idea in any case to have local modifications in your working copy of the stable branch, since you might forgot to commit them back, and then a user might have a non-working dependency.)
     80 1. Make sure your code now still works fine:
     81    i. clean everything ({{{make clean}}})
     82    i. rebuild the autotools files {{{./BuildToolds/run_autotools}}}
     83    i. rerun {{{configure}}}
     84    i. compile and install the code ({{{make install}}})
     85    i. run your tests ({{{make tests}}})
     86 1. If that works fine, commit what is now in your local copy into back into the stable branch of your project ({{{svn commit}}})
     87 1. Create a copy of the current version of your stable branch as a new point release, as described [wiki:pm-svn-releases#CreatingaNewPointRelease here].