docs/manual: add appendix about migratinf from older versions

Hello All!

When we release a new version that voluntarliy breaks compatibility with previous versions, we must document it to hepl the uesr migrate more easily.

In 2017.08, we broke the compatibility with previous versions because we no longer accept an RPATH pointing to $(HOST_DIR)/usr/lib, even though that would technically functional.

Add an appendix about that.

Changes v1 -> v2:
- move all to a single file (Thomas)
- fix typoes (Thomas)

Regards,
Yann E. MORIN.

The following changes since commit 8e4935586226880b1b6d772cd89f8299f5ffc181

package/pngquant: bump version to 2.10.1 (2017-09-05 22:01:35 +0200)

are available in the git repository at:

git://git.buildroot.org/~ymorin/git/buildroot.git

for you to fetch changes up to 8d12cdf3606e18c28219b5e37521aa6facb73605

  docs/manual: add appendix about $(HOST_DIR)/usr (2017-09-05 22:29:44 +0200)

----------------------------------------------------------------
Yann E. MORIN (2):
docs/manual: add appendix about migration from older versions docs/manual: add appendix about $(HOST_DIR)/usr

 docs/manual/appendix.txt                            |  2 +-
 .../{br2-external-converting.txt => migrating.txt}  | 21 ++++++++++++++++++++-
 2 files changed, 21 insertions(+), 2 deletions(-)
 rename docs/manual/{br2-external-converting.txt => migrating.txt} (62%)

.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

... and move the br2-external migration to it.

---
Changes v1 -> v2:
- move in a sing;e file (Thomas)
- fix title typo (ThomaS)

---
 docs/manual/appendix.txt                                   | 2 +-
 docs/manual/{br2-external-converting.txt => migrating.txt} | 9 ++++++++-
 2 files changed, 9 insertions(+), 2 deletions(-)
 rename docs/manual/{br2-external-converting.txt => migrating.txt} (81%)

index 4d4bbecc18..86afa4bdaa 100644
@@ -3,4 +3,4 @@
 
 include::makedev-syntax.txt[]
 include::makeusers-syntax.txt[]
-include::br2-external-converting.txt[]
+include::migrating.txt[]

similarity index 81%
rename from docs/manual/br2-external-converting.txt
rename to docs/manual/migrating.txt
index 831addf5af..5dd83ce8d6 100644
@@ -1,8 +1,15 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
+[[migrating-from-ol-versions]]
+== Migrating from older Buildroot versions
+
+Some versions have introduced backaward incompatibilities. This section
+explains those incompatibilities, and for each explains what to do to
+complete the migration.
+
 [[br2-external-converting]]
-== Converting old br2-external trees
+=== Migrating to 2016.11
 
 Before Buildroot 2016.11, it was possible to use only one br2-external
 tree at once. With Buildroot 2016.11 came the possibility to use more

2.11.0

---
Changes v1 -> v2:
- fix typo in one of the paths (Thomas)

---
 docs/manual/migrating.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)

index 5dd83ce8d6..612fbcb087 100644
@@ -44,3 +44,15 @@ Now, your br2-external tree can be used with Buildroot 2016.11 onward.
 .Note:
 This change makes your br2-external tree incompatible with Buildroot
 before 2016.11.
+
+[[migrating-host-usr]]
+=== Migrating to 2017.08
+
+Before Buildroot 2017.08, host packages were installed in +$(HOST_DIR)/usr+
+(with e.g. the autotools' +--prefix=$(HOST_DIR)/usr+). With Buildroot
+2017.08, they are now installed directly in +$(HOST_DIR)+.
+
+Whenever a package installs an executable that is linked with a library
+in +$(HOST_DIR)/lib+, it must have an RPATH pointing to that directory.
+
+An RPATH pointing to +$(HOST_DIR)/usr/lib+ is no longer accepted.

2.11.0

Hello,

Applied, after fixing a remaining typo in PATCH 1/2: backaward -> backward.

Thanks!

Thomas

Thomas Petazzoni, CTO, Free Electrons
Embedded Linux and Kernel engineering
http://free-electrons.com