src/ceph/doc/dev/corpus.rst

   1
   2 Corpus structure
   3 ================
   4
   5 ceph.git/ceph-object-corpus is a submodule.::
   6
   7  bin/   # misc scripts
   8  archive/$version/objects/$type/$hash  # a sample of encoded objects from a specific version
   9
  10 You can also mark known or deliberate incompatibilities between versions with::
  11
  12  archive/$version/forward_incompat/$type
  13
  14 The presence of a file indicates that new versions of code cannot
  15 decode old objects across that $version (this is normally the case).
  16
  17
  18 How to generate an object corpus
  19 --------------------------------
  20
  21 We can generate an object corpus for a particular version of ceph like so.
  22
  23 #. Checkout a clean repo (best not to do this where you normally work)::
  24
  25         git clone ceph.git
  26         cd ceph
  27         git submodule update --init --recursive
  28
  29 #. Build with flag to dump objects to /tmp/foo::
  30
  31         rm -rf /tmp/foo ; mkdir /tmp/foo
  32         ./do_autogen.sh -e /tmp/foo
  33         make
  34
  35 #. Start via vstart::
  36
  37         cd src
  38         MON=3 OSD=3 MDS=3 RGW=1 ./vstart.sh -n -x
  39
  40 #. Use as much functionality of the cluster as you can, to exercise as many object encoder methods as possible::
  41
  42         ./rados -p rbd bench 10 write -b 123
  43         ./ceph osd out 0
  44         ./init-ceph stop osd.1
  45         for f in ../qa/workunits/cls/*.sh ; do PATH=".:$PATH" $f ; done
  46         ../qa/workunits/rados/test.sh
  47         ./ceph_test_librbd
  48         ./ceph_test_libcephfs
  49         ./init-ceph restart mds.a
  50
  51 Do some more stuff with rgw if you know how.
  52
  53 #. Stop::
  54
  55         ./stop.sh
  56
  57 #. Import the corpus (this will take a few minutes)::
  58
  59         test/encoding/import.sh /tmp/foo `./ceph-dencoder version` ../ceph-object-corpus/archive
  60         test/encoding/import-generated.sh ../ceph-object-corpus/archive
  61
  62 #. Prune it!  There will be a bazillion copies of various objects, and we only want a representative sample.::
  63
  64         pushd ../ceph-object-corpus
  65         bin/prune-archive.sh
  66         popd
  67
  68 #. Verify the tests pass::
  69
  70         make check-local
  71
  72 #. Commit it to the corpus repo and push::
  73
  74         pushd ../ceph-object-corpus
  75         git checkout -b wip-new
  76         git add archive/`../src/ceph-dencoder version`
  77         git commit -m `../src/ceph-dencoder version`
  78         git remote add cc ceph.com:/git/ceph-object-corpus.git
  79         git push cc wip-new
  80         popd
  81
  82 #. Go test it out::
  83
  84         cd my/regular/tree
  85         cd ceph-object-corpus
  86         git fetch origin
  87         git checkout wip-new
  88         cd ../src
  89         make check-local
  90
  91 #. If everything looks good, update the submodule master branch, and commit the submodule in ceph.git.
  92
  93
  94
  95