====== CRAM v0.1 -> CRAM v0.2 ======

===== cram_3rdparty =====

Stayed unchanged. Only got updated (merged PRs from one of the Suturo students).

===== cram_core =====

As the refactoring in v0.2 mostly affected higher level packages of CRAM and didn't influence ''cram_core'' much, there's really not that much you need to do to migrate.

== Step 1: Renaming ASDF systems ==

Search (grep) for ''designators'' and ''process-modules'' in all the ''*.asd'' files of your packages and change ''designators'' (from ''cram_designators'' package) to ''cram-designators'' and ''process-modules'' to ''cram-process-modules''.

== Step 2: Renaming CRAM_REASONING to CRAM_PROLOG ==

Search for ''cram_reasoning'' in all the ''package.xml'' and ''CMakeLists.txt'' files of your packages and change ''cram_reasoning'' to ''cram_prolog''.

Then search for ''cram-reasoning'' in all the ''*.asd'' and ''*.lisp'' files of your packages and change ''cram-reasoning'' to ''cram-prolog''. Also, search for ''crs'' in all the ''*.lisp'' files and change it to ''prolog''.

== Step 3: designator properties as keywords ==

Search for all ''make-designator'' and ''with-designators'' and change the type of the designator from simple symbol to a keyword, e.g. 
<code lisp>
(make-designator 'location '((on table)))
</code>
should turn into
<code lisp>
(make-designator :location '((on table)))
</code>

Next search for all ''make-designator'', ''with-designators'' and ''(desig-prop ?'' calls in all your Lisp files and change the designator properties there from simple symbols to keywords, e.g. '' 'on'' should become '':on''. Also, search for all ''desig-props'' in all your Lisp files and get rid of them, e.g.
<code lisp>
(desig-prop ?designator (desig-props:to desig-props:see))
</code>
should turn into
<code lisp>
(desig-prop ?designator (:to :see))
</code>

Finally, you can search for ''def-desig-package'' in all your ''package.lisp'' files and get rid of ''def-desig-package'' and ''designator-properties'' there. This is not obligatory but it will make your code cleaner. E.g.:
<code lisp>
(desig-props:def-desig-package :cram-designators
    (:use #:common-lisp #:cram-reasoning #:cut)
    (:nicknames :desig)
    (:desig-properties #:obj #:location #:object #:pose #:of #:at
                       #:type #:trajectory #:action #:constraints))
</code>
should turn into
<code lisp>
(defpackage :cram-designators
    (:use #:common-lisp #:cram-reasoning #:cut)
    (:nicknames :desig))
</code>

== Step 4: one bracket less in WITH-DESIGNATORS ==

Finally, search for all ''with-designators'' in your ''*.lisp'' files and get rid of one extra bracket there, e.g.
<code lisp>
(with-designators
   ((open-loc (:location `((:to :open) (:to :reach)
                           (:obj ,?obj)))) ; <- 4 brackets in the end
    (open-action (:action `((:type :trajectory)
                            (:to :open) (:obj ,?obj)
                            (:angle ,?angle)))))
</code>
should turn into
<code lisp>
(with-designators
   ((open-loc :location `((:to :open) (:to :reach)
                          (:obj ,?obj))) ; <- 3 brackets in the end
    (open-action :action `((:type :trajectory)
                           (:to :open) (:obj ,?obj)
                           (:angle ,?angle))))
</code>

The idea behind this change was that the less brackets you have the better and that this way ''with-designators'' will look a lot more like ''make-designator'', e.g.
<code lisp>
(with-designators
  ((some-location :location '((:some :where)))))
</code>
<code lisp>
   (make-designator :location '((:some :where)))
</code>
If you don't like this change, please complain.


**Hint:** there are some awesome tutorials on ''cram_core'' on this website, all the tutorials that are under "Beginner tutorials" category [[http://cram-system.org/tutorials|here]] use solely ''cram_core'' and demonstrate the features of CRAM, check them out.


===== cram_bridge =====

The ''cram_bridge'' repository / metapackage had enormous dependencies on the other CRAM / IAI packages - you needed the whole CRAM and a bunch of robot drivers and some experimental code just to be able to use a Lisp JSON Prolog implementation or the semantic logging mechanism. To avoid that the three most widely used packages from there got separated into their own repositories: [[https://github.com/cram2/cram_beliefstate|cram_beliefstate]], [[https://github.com/cram2/cram_json_prolog|cram_json_prolog]], [[https://github.com/cram2/cram_moveit|cram_moveit]].

===== cram_highlevel and cram_physics ====

There were way too many changes in the higher level packages to write a comprehensive migration guide but here is a general overview. (If you have your own code that uses ''cram_highlevel'' or ''cram_physics'' you are strongly advised to get in touch with [[/user/gayane_kazhoyan|Gaya]] and get her to help you with migration.)

There used to be two high-level packages: ''cram_highlevel'' and ''cram_physics'', now there are four: ''cram_plans'', ''cram_semantic_maps'', ''cram_3d_world'', ''cram_costmaps''. The functionality that used semantic environment maps from KnowRob in ''cram_highlevel'' got separated into ''cram_semantic_maps'' such that if you only want, say the plan library, you wouldn't have to download the whole semantic map business and have to compile that. The same with the specific costmaps that were in ''cram_physics'', they are now in ''cram_costmaps'', also PR2-specific code of ''cram_physics'' went to ''cram_pr2''.

To get a better picture of the current state take a look at [[https://docs.google.com/spreadsheets/d/1FTPf2HjlM18BMpSwd9GKimZCcmlNYAZLuQPkJAROVLg/edit#gid=0|this spreadsheet]]
or at [[https://github.com/cram2/cram_projection_demos/blob/master/cram-with-projection.rosinstall|this rosinstall file]].

There is a tutorial on how you can use the semantic environment maps with minimal dependencies in your own code [[http://cram-system.org/tutorials/intermediate/semantic_environment_map|here]].

Soon there will be a tutorial on writing your own plan library with minimal dependencies, so stay tuned.