On head, the following things have been commited on top of this:
* patches/, which is a directory with a set of patches, and a series file
listing the order, as generated by quilt
-* .pc/, which is a tree of files that quilt uses to keep control of its state.
- It contains a list of applied patches, and one directory per patch,
- containing a tree of hardlinked files that were added to the patchset, and
- a .pc file listing all files part of the patchset.
* the result of having all these patches commited (ie, quilt push -a) to the
ffmpeg tree.
-Both the actually patched CVS ffmpeg code as well as the .pc dir need to be
-commited to CVS so the state of quilt wrt. the source is in sync.
+The patched CVS ffmpeg code needs to be commited to CVS so that a checkout
+gives the patched code
+
+The Quilt state .pc hidden directory must NOT be committed to CVS, because
+having CVS subdirs inside it confuses the hell out of quilt and causes it to
+start storing diffs against CVS Entries files, and all hell breaks loose
+
+THE WARNING
+-----------
+
+***
+
+NEVER EVER commit stuff in gst-libs/ext/ffmpeg UNLESS your quilt stack is
+completely applied !
+This means, ALWAYS make sure quilt push -a has been run without problems.
+
+What's more, if you want to be on the safe side, make sure that you can
+unapply and reapply without problems, by running quilt pop -a then
+quilt push -a.
+
+The ONLY exception to this is when you're working on a branch to update
+the upstream source you're working with.
+
+***
THE WAY
-------
-
- If you want to hack on our copy of the FFmpeg code, there are some basic
rules you need to respect:
- you need to use quilt. If you don't use quilt, you can't hack on it.
NO files listed with question mark. If there are, somebody before you
probably made a mistake. To manage the state correctly, it is vital that
none of the files are unknown to CVS.
- - if you want to add a file to a patchset, you need to:
- - be in the right patchset
- - quilt add (file)
- - cvs add .pc/(patchsetname)/(file)
- - cvs commit .pc/(patchsetname) (to update the state of quilt in cvs)
- - edit the file
- - cvs add the file if it doesn't exist yet
- - quilt refresh
- - quilt push -a (This one is IMPORTANT, otherwise you'll have a huge diff)
- - cvs commit
- - if you want to add a patchset, you need to:
- - go over the procedure with thomas to check it's correct
- - decide where in the stack to put it. ask for help if you don't know.
- - go there in the patch stack (use quilt pop/push)
- - quilt new (patchsetname).patch (don't forget .patch !)
- - quilt add (files)
- - cvs add .pc/(patchsetname) the whole tree
- - cvs commit .pc/(patchsetname)
- - quilt refresh
- - quilt push -a
- - cvs commit
- - cvs diff (to check if any of the files are unknown to CVS; if they are,
- you need to add them to CVS)
+
+FIRST TIME:
+ - The quilt state is kept in a hidden dir in the gst-libs/ext/ffmpeg dir,
+ but this hidden dir can't be kept in CVS because it confuses patch. Hence
+ when you get a clean gst-ffmpeg checkout you have an ffmpeg tree with
+ patches applied, but no quilt metadata to modify it with.
+
+ - You need to create the quilt metadata in your checkout:
+ 1) Unroll the quilt patches. In gst-libs/ext/ffmpeg, run:
+
+ tac patches/series | while read p; do patch -p1 -R < "patches/$p"; done
+
+ 2) Now, push all the patches to quilt and it will apply them, but now with
+ the appropriate stored metadata:
+
+ quilt push -a
+
+- if you want to add a file to a patchset, you need to:
+ - be in the right patchset
+ - quilt add (file)
+ - cvs add .pc/(patchsetname)/(file)
+ - cvs commit .pc/(patchsetname) (to update the state of quilt in cvs)
+ - edit the file
+ - cvs add the file if it doesn't exist yet
+ - quilt refresh
+ - quilt push -a (This one is IMPORTANT, otherwise you'll have a huge diff)
+ - cvs commit
+
+- if you want to add a patchset, you need to:
+ - go over the procedure with thomas to check it's correct
+ - decide where in the stack to put it. ask for help if you don't know.
+ - go there in the patch stack (use quilt pop/push)
+ - quilt new (patchsetname).patch (don't forget .patch !)
+ - quilt add (files)
+ - cvs add .pc/(patchsetname) the whole tree
+ - cvs commit .pc/(patchsetname)
+ - quilt refresh
+ - quilt push -a
+ - cvs commit
+ - cvs diff (to check if any of the files are unknown to CVS; if they are,
+ you need to add them to CVS)
+
+THE UPSTREAM
+------------
+At some points you want to update the upstream snapshot code to a newer date.
+This is easy if you follow the steps outlined here, but make sure to follow
+them correctly !
+
+- find a good CVS snapshot date for upstream, one that is known to work.
+ You're going to save yourself quite a bit of trouble if you verify this
+ first !
+- check it out to a local directory:
+ cvs -z9 -d:pserver:anonymous@mplayerhq.hu:/cvsroot/ffmpeg export -D '2004-04-11 23:00 GMT' ffmpeg
+- compile it and test it, make sure it works
+
+- in gst-ffmpeg/gst-libs/ext/ffmpeg:
+ - Pre-flight checks:
+ - first make sure you don't have local changes, all files are either in
+ CVS or in .cvsignore patch, the whole quilt stack is applied, and stuff
+ works.
+ - do a quilt pop -a and quilt push -a to verify everything is ok.
+
+ - Branch and rollback:
+ - tag HEAD with the branch root point:
+ cvs tag BRANCH-UPDATE-CVS-2004-04-11-23-00-ROOT
+ - branch:
+ cvs tag -b BRANCH-UPDATE-CVS-2004-04-11-23-00
+ - FIXME: lock cvs HEAD
+ - update local copy to branch:
+ cvs update -r BRANCH-UPDATE-CVS-2004-04-11-23-00
+ - peel off all patches:
+ quilt pop -a
+ - commit this
+ cvs commit
+ - check
+ cvs diff
+ you should only have ? for files that are generated somehow (binaries,
+ build files, ...)
+ you get warnings about cvs not finding files to diff that are in .pc
+ or generated by your patches
+
+
+ - if you want, you can now compare this state of CVS (which should
+ be last upstream CVS combined with your local unapplied quilt state)
+ - remember to NOT do cvs update from here on, since you popped your quilt
+ state all your added files that are also in CVS are not locally present.
+
+ - sync with upstream:
+ - in a temp dir, redo the export:
+ cd ..
+ mkdir tmp
+ cd tmp
+ cvs -z9 -d:pserver:anonymous@mplayerhq.hu:/cvsroot/ffmpeg export -D '2004-04-11 23:00 GMT' ffmpeg
+ - rsync it over the old ffmpeg tree
+ rsync -arv ffmpeg ..
+ - go back and commit this new snapshot
+ cd ../ffmpeg
+ cvs commit
+ - check if any new files got added that you should add to cvs
+ cvs diff
+ This will list a lot of local files missing, from your quilt state,
+ which you shouldn't worry about. Just inspect all the ?'s and add
+ files to cvs that belong to upstream and should be in cvs.
+ - if everything's ok and commited, tag the state:
+ cvs tag UPSTREAM-CVS-2004-04-11-23-00
+
+ - reapply and fix quilt patches one by one
+ - try applying one
+ quilt push
+ - if that didn't work, inspect the patch and figure out how to fix it:
+ - if the patch got applied upstream completely, quilt push will tell
+ you the patch looks like a reverse patch. In that case you can
+ remove the patch from your patches file (patches/series), and
+ remove the .pc/$(patchname) and patches/$(patchname).patch files from
+ cvs.
+ - if the patch conflicts somehow, you can force application with
+ quilt push -f
+ and then resolve all the rejects, and fix the patch completely.
+ Then refresh quilt state with
+ quilt refresh
+ - when the patch is succesfully removed or reworked, commit current state
+ to CVS, then check again if nothing is missing using cvs diff, and
+ resolve problems/apply missing files from your quilt state/...
+
+ - after reapplying your complete quilt state, test locally if the complete
+ gst-ffmpeg module now works. Compile and test. Resolve all problems
+ (upstream errors, missing symbols, missing files, ...) until you have
+ a working module. commit again.
+
+ - merge to head:
+ - update locally back to head
+ cvs update -A
+ - FIXME: unlock cvs HEAD
+ - merge from your branch
+ cvs update -j BRANCH-UPDATE-CVS-2004-04-11-23-00
+ - commit
+ cvs commit
+ - check for diffs
+ cvs diff
+ - tag merge point
+ cvs tag BRANCH-UPDATE-CVS-2004-04-11-23-00-MERGE
+ - add upstream date to "THE RECORDS" below
+
+ - get a drink
THE PLUGIN
----------
Some notes on how ffmpeg wrapping inside GStreamer currently works:
* gstffmpeg{dec,enc,demux,mux}.c are wrappers for specific element types from
their ffmpeg counterpart. If you want to wrap a new type of element in
- ffmpeg (e.g. the URLProtocol things), then you'd need to write a new
wrapper file.
-
-* gstffmpegcolorspace.c is a wrapper for one specific function in ffmpeg:
- colorspace conversion. This works different from the previously mentioned
- ones, and we'll come to that in the next item. If you want to wrap one
- specific function, then that, too, belongs in a new wrapper file.
-
-* the important difference between all those is that the colorspace element
- contains one element, so there is a 1<->1 mapping. This makes for a fairly
- basic element implementation. gstffmpegcolorspace.c, therefore, doesn't
- differ much from other colorspace elements. The ffmpeg element types,
- however, define a whole *list* of elements (in GStreamer, each decoder etc.
- needs to be its own element). We use a set of tricks for that to keep
- coding simple: codec mapping and dynamic type creation.
+ The ffmpeg element types, define a whole *list* of elements (in
+ GStreamer, each decoder etc. needs to be its own element).
+ We use a set of tricks for that to keep coding simple: codec
+ mapping and dynamic type creation.
* ffmpeg uses CODEC_ID_* enumerations for their codecs. GStreamer uses caps,
which consists of a mimetype and a defined set of properties. In ffmpeg,
* there's lots of things that still need doing. See the TODO file for more
information.
+
+THE RECORDS
+-----------
+- list of snapshots used:
+
+ CVS-2004-04-11-23-00
+ * other updates people didn't enter :)
+ CVS-2006-02-17-04-00
+
+THE REMINDERS
+-------------
+* the initial ffmpeg checkout was imported using:
+ - get CVS ffmpeg
+ cvs -z3 -d:pserver:anonymous@mplayerhq.hu:/cvsroot/ffmpeg co -D '2004-03-09 06:00 GMT' ffmpeg
projects / platform / upstream / gst-libav.git / blobdiff