Changes between Version 7 and Version 8 of pm-svn-externals


Ignore:
Timestamp:
Aug 21, 2007 12:54:43 PM (13 years ago)
Author:
lou
Comment:

Noticed a couple of typos and ended up doing a general cleanup.

Legend:

Unmodified
Added
Removed
Modified
  • pm-svn-externals

    v7 v8  
    55== Basics ==
    66
    7 Externals 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.
     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 using URLs) are also checked out, into subdirectories 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 ensure that people get a compatible version of a dependency --- the latest development version in the {{{trunk}}} of a dependency might not work with the code of the package one is trying to download and compile, if the development of the dependency has introduced incompatible changes.  Also, we can ensure in this way that point releases will 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 ensure that COIN packages which require other COIN packages obtain those packages 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 [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:
     15'''Our policy for managing externals in COIN is that we put a file called {{{Externals}}} into a directory. The {{{svn:externals}}} property for the directory is then set by manual execution of the {{{svn propset}}} command.'''
     16
     17For 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:
    1618
    1719{{{
     
    2325}}}
    2426
    25 The 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.
     27The 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 location of the dependency in a repository.
    2628
    2729== Important Considerations For Externals ==
    2830
    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.''
     31'''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 rely on the project manager's discipline to adhere to this convention.''
    3032
    31 In 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.
     33In the above example we see that all externals have been set to things that are not going to change at some later point in time:  By [wiki:pm-svn-releases convention], subdirectories in the {{{releases/}}} directory for each COIN project are [wiki:pm-svn-branches tags], ''i.e.'', they should never be changed once they have been created. Pointing to specific {{{releases/}}} subdirectories is recommended.  If, for some reason, the required code is not available in a {{{releases/}}} subdirectory, the externals definition ''must'' specify a particular subversion repository revision number using the {{{-r}}} flag, as shown in the {{{MSVisualStudio}}} entry above.
    3234
    3335== Manipulating Externals ==
    3436
    35 To 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
     37To 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, move into the {{{Clp}}} base directory and issue the command
    3638
    3739{{{
     
    3941}}}
    4042
    41 If you want to change the value of a property, you use the {{{svn propset}}} command.  In COIN, we find it good practice to use the Externals file, so that users that don't have {{{svn}}} can also see  the dependencies. You can edit the {{{Externals}}} file to add or remove external dependencies. Once you have edited the {{{Externals}}} file in a directory, you can use this file to update the
    42 {{{svn:externals}}} property with the command
    43 {{{
     43If you want to change the value of a property, you use the {{{svn propset}}} command.  In COIN, we find it good practice to use an Externals file, so that users who do not have {{{svn}}} can easily see the dependencies. Changing external dependencies is a three-step process:
     44  1. Edit the {{{Externals}}} file to modify, add, or remove lines specifying external dependencies.
     45  1. Use the {{{Externals}}} file to update the {{{svn:externals}}} property with the command
     46  {{{
    4447svn propset svn:externals -F Externals .
    4548}}}
    46 The {{{-F}}} flag tells {{{svn}}} to take the content of the file as the value of the property to be set.  Once the {{{svn:externals}}} property has been updated, new dependencies added to the {{{Externals}}} file will be downloaded at the next {{{svn update}}}
    47 command, and dependencies removed from the
    48 {{{Externals}}} file will be removed from subversion's records.
    49 (However, the directories must be removed by hand, after you've run
    50 {{{svn update}}}.)
     49  The {{{-F}}} flag tells {{{svn}}} to take the content of a file (in this case, {{{Externals}}}) as the value of the property to be set. That final `{{{.}}}' is important! The {{{svn propset}}} command requires that you explicitly specify the directory where the property change is to be applied.
     50  1. Once the {{{svn:externals}}} property has been updated, the changes will be applied at the next {{{svn update}}} command: changed dependencies will be updated, new dependencies will be downloaded, and dependencies removed from the {{{svn:externals}}} property will be removed from subversion's records. (However, the directories must be removed by hand, after you've run {{{svn update}}}.)
    5151
    5252Finally, if you decide to completely eliminate externals in a directory, you should delete the {{{Externals}}} file, and delete the {{{svn:externals}}} property with
     
    5858'''Note:''' If you have configured your local copy with the {{{--enable-maintainer-mode}}} and have {{{svn}}} available on your system, the Makefiles will automatically do the {{{svn propset}}} command for you when you change the {{{Externals}}} file.  However, you will need to run the {{{svn update}}} command by hand.
    5959
     60Keep in mind that subversion knows nothing of the COIN convention for using an Externals file.
     61Nothing will change until you run a subversion command to change the {{{svn:externals}}} property.
     62
    6063More 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.
    6164
    6265== Preparing Externals For A Point Release ==
    6366
    64 Typically, 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).
     67Typically, a stable version of a COIN project that depends on other COIN projects will specify a particular version (subdirectory) in the {{{stable/}}} directory of each dependency, so that a user will always receive the latest improvements and bugfixes for each dependency.  By convention, the compilation should not break; a project manager should ensure compatibility of the project's code with the externals selected for use in a particular stable version.
    6568
    6669If you now want to create a new point release from the latest version in your stable branch, we suggest you follow these steps:
    6770
    68  1. Get a local copy of your stable branch (you probably have it already)
     71 1. Get a local copy of your stable branch (you probably have it already).
    6972 1. Make a backup copy of your current {{{Externals}}} file
    70  1. For each dependency in your Externals file find the latest point release nuymber.  You can do this for example using
    71 {{{
     73 1. For each dependency in your Externals file find the latest point release number.  You can do this for example using
     74 {{{
    7275svn list https://projects.coin-or.org/svn/DepPrcjt/releases
    73 }}}
     76 }}}
    7477 where {{{DepPrcjt}}} is the name of the dependency project.
    75  1. Change entries for all externals in the Externals file to point to the latest point releases.
    76  1. Update the actual subversion {{{svn:externals}}} property of the directory:
    77 {{{
    78 svn pset svn:externals -F Externals .
    79 }}}
    80  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.)
     78 1. Change the entry for each external in the Externals file to point to the latest point release for the external.
     79 1. Update the {{{svn:externals}}} property of the directory:
     80 {{{
     81svn propset svn:externals -F Externals .
     82 }}}
     83 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 first arrange with the project manager for the dependency to have your changes committed into the dependency's repository.  It is not a good idea in any case to have local modifications in your working copy of the stable branch, since you might forget to commit them back, and then a user might download a non-working dependency.)
    8184 1. Make sure your code now still works fine:
    82     i. clean everything ({{{make clean}}})
    83     i. rebuild the autotools files ({{{./BuildToolds/run_autotools}}})
    84     i. make sure (using {{{svn status}}}) that this '''did not change any files in the externals subdirectories.'''  (If it did change, say, a {{{configure}}} file, it means that the dependency has not used the same version of !BuildTools that you are using.  '''This must be reconciled first'''.)
    85     i. rerun {{{configure}}}
    86     i. compile and install the code ({{{make install}}})
    87     i. run your tests ({{{make tests}}}) and do whatever you do to convince yourself that it works.
    88  1. If that works fine, commit what is now in your local copy into back into the stable branch of your project ({{{svn commit}}})
    89  1. As a sanity check, you might want to try if the code now in your stable branch compiles and runs fine on a different machine ({{{svn update}}} and {{{make tests}}} on the other machine)
     85    i. Clean everything ({{{make clean}}}).
     86    i. Rebuild the autotools files ({{{./BuildToolds/run_autotools}}}).
     87    i. Make sure ({{{svn status}}}) that the autotools rebuild '''did not change any files in the externals subdirectories.'''  If the rebuild changed, ''e.g.'', a {{{configure}}} file, it means that the dependency does not use the same version of !BuildTools that you are using.  '''This must be reconciled first'''.
     88    i. Rerun {{{configure}}}.
     89    i. Compile and install the code ({{{make install}}}).
     90    i. Run your tests ({{{make tests}}}) and do whatever you do to convince yourself that your project's code works correctly.
     91 1. If that works fine, commit what is now in your local copy into back into the stable branch of your project ({{{svn commit}}}).
     92 1. To confirm portability and act as a sanity test, you might want to check that the code now in your stable branch compiles and runs fine on a different machine ({{{svn update}}} and {{{make tests}}} on the other machine).
    9093 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].
    9194 1. Restore your original {{{Externals}}} file from your backup created in Step 2 above and restore the previous (non-release) externals:
    92 {{{
    93 svn pset svn:externals -F Externals .
    94 }}}
    95  1. Commmit the restored externals to your stable branch ({{{svn commit}}})
     95 {{{
     96svn propset svn:externals -F Externals .
     97 }}}
     98 1. Commit the restored externals to your stable branch ({{{svn commit}}}).