Notes on what to do when merging a BSP.

1 files changed, 73 insertions, 0 deletions

diff --git a/c/src/lib/libbsp/MERGE.PROCEDURE b/c/src/lib/libbsp/MERGE.PROCEDURE
new file mode 100644
index 0000000000..3eabe41f9b
--- /dev/null
+++ b/c/src/lib/libbsp/MERGE.PROCEDURE
@@ -0,0 +1,73 @@
+#
+#  $Id$
+#
+
+When adding a BSP to the RTEMS tree, there is usually some cleanup
+to be done. 
+
+=========================================================================
+
+Add an entry to ACKNOWLEDGEMENTS.
+
+Send letter with permission to distribute the BSP with RTEMS.
+
+Verify all test link.
+
+Remove compilation warnings.
+
+Make sure that all files submitted are really intended to do into
+the distribution. For example, you may have a myfile.S produced by
+gcc -S myfile.c.
+
+=========================================================================
+This section of the file describes how to run the acpolish script to
+check Makefile style and construction compliance.
+
+The BSP's still apply RTEMS's old autoconf configuration. The only thing
+that have changed are some details inside the Makefile.ins and some details
+in make/custom/<bsp>.cfg. Acpolish should be able to convert 4.0.0
+Makefile.in into new style Makefile.ins. However, sometimes acpolish has
+problems/contains bugs, which require manual intervention. There is no tool
+to adapt a BSP's <bsp>.cfg, but this shouldn't be a problem for you.
+
+Therefore, this is my coarse recipe to merge BSPs is:
+
+1. Copy a BSP's files and directories to appropriate directories.
+
+2. Manually run acpolish on each Makefile.in and check the output, eg:
+cd some_subdir
+ /path_to_RTEMS/tools/update/acpolish < Makefile.old > Makefile.new
+
+Check Makefile.new for correctness, evtl. edit it, then re-run acpolish
+again:
+/path_to_RTEMS/tools/update/acpolish < Makefile.new > Makefile.in
+
+Compare Makefile.new against Makefile.in. These must not differ, if they
+do, edit Makefile.new until the Makefile.in generated by re-running
+acpolish on Makefile.new does not differ from the freshly generated
+Makefile.in. If they differ permanently, then you probably are affected
+bugs in acpolish (This happens for some styles of conditionals).
+
+This sounds much worser than it actually is, because the bugs in acpolish
+only hit very seldom. Furthermore, BSPs normally only contain a few
+Makefile.ins, therefore individually running acpolish should be tolerable.
+
+3. If a BSP contains tools, you have to convert its configuration to
+automake manually. Typically these tools are rather simple, therefore a
+tool's configuration applies standard automake Makefile.ams and
+configure.ins. RTEMS should contain enough examples which could serve as
+templates for this (My advice: Try to avoid preinstallation and
+installation to the temporary installation tree whenever possible; Don't
+forget to add all sources which do not get installed installed by automake
+to automake's EXTRA_DIST, e.g. noinst_SCRIPTS, noinst_DATA have to be added
+to EXTRA_DIST).
+
+Please let me know if you meet problems and if we/I can fix them. I
+consider acpolish to be an internal developer's and maintainer's helper
+script, which was never intended to be of general use, which is why I am
+not much concerned about bugs in it.
+
+Ralf.
+
+=========================================================================
+