Changes between Version 2 and Version 3 of explainSvn


Ignore:
Timestamp:
Dec 29, 2015, 3:43:16 AM (9 years ago)
Author:
dmik
Comment:

Add the import from a foreign repo case

Legend:

Unmodified
Added
Removed
Modified

  • explainSvn

    v2 v3  
    2323svn mkdir --parents http://svn.netlabs.org/repos/ports/pixman/vendor/current -m "pixman: Create vendor tree."
    2424}}}
    25 The real-life result of this step is in r1222.
     25The real-life result of this step is in r1228.
    2626
    2727Then you need to check out the vendor tree to your file system:
    … …  
    3131}}}
    3232
    33 The next step is to import original sources. There are two possible cases: using a tarball from the vendor or taking the sources right from the vendor's source repository (SVN, GIT, HG, etc). There is one essential difference between these cases: the tarball will usually contain pre-generated sources necessary for the build (and sometimes also the documentation) while the repository doesn't contain these files assuming they will be regenerated by the developer. The vendor's repository looks like a more suitable source for importing (because it makes no sense to store generated files in a version control system). But most projects in this '''ports''' repository are Linux-oriented and we don't have all the tools necessary to generate build files (and, especially, documentation), so sometimes it is more desirable to take a tarball for importing (and remove files we can generate on OS/2 later on).
     33The next step is to import original sources. There are two possible cases: using a tarball from the vendor or taking the sources right from the vendor's source repository (SVN, GIT, HG, etc). There is one essential difference between these cases: the tarball will usually contain pre-generated sources necessary for the build (and sometimes also the documentation) while the repository doesn't contain these files assuming they will be regenerated by the developer. The vendor's repository is a '''preferred''' source for importing (because it makes no sense to store generated files in a version control system). But sometimes it's not possible, either because the vendor repository is not accessible or because not all files can be re-generated on OS/2 due to the lack of some Linux tools that hasn't been ported to OS/2 yet.
     34
     35=== Importing from a foreign repository
     36
     37Fortunately, the pixman project a the public repository which is located here: http://cgit.freedesktop.org/pixman/. It's a GIT repository, so you need the `git` package to check it out. You also need to define a version you want to import and a tag corresponding to it. In our case it's version 0.32.8 (the latest stable one at the time of writing) and the respective tag is `pixman-0.32.8`. To check out this tag to `vendor-current`, run the following command:
     38{{{
     39git clone --depth=1 http://anongit.freedesktop.org/git/pixman.git -b pixman-0.32.8 pixman/tmp
     40rm -rf pixman/tmp/.git
     41mv `find pixman/tmp/ -maxdepth 1 -mindepth 1` pixman/vendor-current/
     42rmdir pixman/tmp
     43}}}
     44
     45=== Importing from a tarball
    3446
    3547Let's assume we downloaded a tarball of the version we want to import, e.g.`pixman-0.32.8.tar.gz` for the pixman library version 0.32.8. Now unpack it to `pixman/vendor-current`:
    … …  
    3850}}}
    3951
     52=== Committing the tree
     53
    4054Now commit all the original files with these commands:
    4155{{{
    4256cd pixman/vendor-current
    43 svn add *
     57svn add . --force
    4458svn commit
    4559}}}
    … …  
    4862pixman: Import version 0.32.8 from vendor.
    4963
    50 Source URL: http://cairographics.org/releases/pixman-0.32.8.tar.gz
     64Source URL: http://cgit.freedesktop.org/pixman/tag/?id=pixman-0.32.8
    5165}}}
    52 Note that you should specify the exact download URL of the tarball (or the URL of the repository tag) you used for the import operation in this commit — it may be needed to get the this tarball later to check that everything was properly imported etc. Check r1223 for the real-life example.
     66Note that you should specify the exact URL of the corresponding repository tag (or the download URL of the tarball, like http://cairographics.org/releases/pixman-0.32.8.tar.gz) you used for the import operation in this commit — it may be needed to get the original vendor source later to check that everything was properly imported etc. Check r1229 for the real-life example.
    5367
    54 Now, in case if the sources were imported from a tarball, it's time to detect which files can be regenerated and should be removed. If the project you are importing is autotools-based, then the best way to do it is to unpack the tarball into a temporary directory and try to run the following command from there (unless there is a special script like `autogen.sh`, `bootstrap` and similar in which case you should use that script instead). This also assumes you have `autoconf`, `automake` and `libtool` packages installed:
     68The next step is to mark the result of the new vendor import with a version tag for further reference, like this (see r1230):
     69{{{
     70svn copy http://svn.netlabs.org/repos/ports/pixman/vendor/current http://svn.netlabs.org/repos/ports/pixman/vendor/0.32.8 -m "pixman: Tag version 0.32.8 from vendor."
     71}}}
     72
     73Now it's time to start off the project trunk where OS/2 development will actually take place (r1231):
     74{{{
     75svn copy http://svn.netlabs.org/repos/ports/pixman/vendor/0.32.8 http://svn.netlabs.org/repos/ports/pixman/trunk -m "pixman: Start off trunk from version 0.32.8 from vendor."
     76}}}
     77
     78=== Removing generated files ===
     79
     80This step is applicable only if the sources were imported from a tarball. In this case it is necessary to detect which files can be re-generated and should be removed. If the project you are importing is autotools-based, then the best way to do it is to unpack the tarball into a temporary directory and try to run the following command from there (unless there is a special script like `autogen.sh`, `bootstrap` and similar in which case you should use that script instead). This also assumes you have `autoconf`, `automake` and `libtool` packages installed:
    5581{{{
    5682autoreconf -fvi
    … …  
    75101}}}
    76102
    77 Now you first remove these files from under SVN control with `svn rm FILENAME` (be careful not to remove necessary files!) and then commit the result with this command:
     103Now you first remove these files from under SVN control with `svn rm FILENAME` or with `svn rm --targets FILE` where FILE contains all the files to remove, one per line (be careful not to remove necessary files!), then commit the result with this command:
    78104{{{
    79105svn commit -m "pixman: Remove generated files for version 0.32.8 from vendor."
    80106}}}
    81 The result is in r1224.
     107The example result is in r1224.
    82108
    83109Note that another important reason to re-generate as much files as possible on the developer's machine (besides saving space and history in the SVN repository) is to make sure the generated files will get OS/2-specific changes necessary for the build to work correctly. This is needed since not all OS/2 patches to the toolchain reach upstream repositories in time and hence the generated file provided in the tar ball may not know about OS/2 at all and will simply not work. Besides this, a recent version of autotools may have some important fix to apply and so on. So the developer should always re-generate these files locally before performing a build.
    84110
    85 The next step is to mark the result of the new vendor import with a version tag for further reference, like this ( see r1225):
    86 {{{
    87 svn copy http://svn.netlabs.org/repos/ports/pixman/vendor/current http://svn.netlabs.org/repos/ports/pixman/vendor/0.32.8 -m "pixman: Tag version 0.32.8 from vendor."
    88 }}}
    89 
    90 Now it's finally time to start off the project trunk where OS/2 development will actually take place (r1226):
    91 {{{
    92 svn copy http://svn.netlabs.org/repos/ports/pixman/vendor/0.32.8 http://svn.netlabs.org/repos/ports/pixman/trunk -m "pixman: Start off trunk from version 0.32.8 from vendor."
    93 }}}
     111=== Checking out working copy
    94112
    95113Now you can check out the trunk locally with:
    … …  
    99117}}}
    100118and start working on patches to make it build and work on OS/2.
     119
     120Don't forget to re-generate the build files as described above.
    101121
    102122Changes should be committed to the trunk grouped into logically connected chunks, one commit per each logical modification using this commit message as a template: