[yocto] [eclipse-poky][PATCH] Update and enhance README.txt
Tim Orling
timothy.t.orling at linux.intel.com
Fri Oct 21 13:39:46 PDT 2016
* Move scripts/readme.txt -> README.txt
* Update information which had gotten out of date
* Remove non-generic instructions
* Augment the description of the work flow
- Clarify command line options for the scripts
- Describe how to update to a newer Eclipse release
- Mention the Eclipse mailing lists to help stay informed
[YOCTO #10111]
Signed-off-by: Tim Orling <timothy.t.orling at linux.intel.com>
---
README.txt | 250 +++++++++++++++++++++++++++++++++++++++++++++++++++++
scripts/readme.txt | 71 ---------------
2 files changed, 250 insertions(+), 71 deletions(-)
create mode 100644 README.txt
delete mode 100644 scripts/readme.txt
diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..c7d1fa5
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,250 @@
+Note: PART I and PART II can be skipped if you have already done that.
+
+Part I: Base environment setup
+
+I-1. Install Build Dependencies
+
+I-1.1 Fedora
+
+ sudo dnf install java-1.8.0-openjdk xsltproc wget tar make git
+
+I-1.2 Ubuntu
+
+ sudo apt-get install openjdk-8-jdk xsltproc wget tar make git
+
+I-1.3 OpenSUSE
+
+ sudo zypper install java-1_8_0-openjdk xsltproc wget tar make git
+
+
+I-3. Proxy Settings (If you're behind some firewall)
+
+ The currently recommended solution is to use Chameleonsocks:
+
+ https://github.com/crops/chameleonsocks
+
+ The legacy method of handling proxy settings is included in Appendix A.
+
+
+I-4. Get the Source Code for the Yocto Project Eclipse Plugin
+
+ git clone git://git.yoctoproject.org/eclipse-poky.git
+
+ The scripts used for building, including on the auto builder, are under
+ the "scripts" directory.
+
+ The repo has several branches, for different releases of Eclipse (e.g.
+ "neon-master") and also for difference releases of the Yocto Project
+ (e.g. "neon/morty").
+
+
+Part II: Setup the Build Environment
+
+II-1. Modify the scripts/setup.sh to set appropriate proxy settings.
+
+ If you are not using Chameleonsocks, set PROXY to a http proxy URL
+ and PORT to the port number. Comment out these 2 variables if proxy
+ is not required.
+
+
+II-2. Run setup.sh Script
+
+ Run <path to>/scripts/setup.sh to set up the build environment.
+ This will install the Eclipse SDK and relevant plugins required to build
+ the Yocto Project Eclipse plug-ins. It will also create a convenience
+ symbolic link to the Eclipse executable.
+
+ If you are working on a newer Eclipse release, where the upstream has not
+ yet been mirrored to http://downloads.yoctoproject.org/eclipse/, you
+ should instead run:
+
+ <path to>/scripts/setup.sh --upstream
+
+
+Part III: Build & Install Yocto Eclipse plug-in
+
+III.1 Build the Yocto Eclipse Plug-in
+
+ To build the Yocto Eclipse plug-in, simply run
+
+"ECLIPSE_HOME=<eclipse path> <path to>/scripts/build.sh <plugin branch or tag name> <documentation branch or tag name> <release name> 2>&1 | tee -a build.log"
+
+ Note that this will clone the indicated branch of yocto-docs from
+ git.yoctoproject.org. If you pass in an invalid branch/tag, the build
+ will fail.
+
+ The <eclipse path> is the absolute path where you installed Eclipse
+ in step II-2.
+
+ If successful, three files will be generated in the directory where
+ you invoked the "build.sh" script:
+ org.yocto.doc-<release name>-<date>.zip,
+ org.yocto.sdk-<release name>-<date>.zip and
+ org.yocto.sdk-<release name>-<date>-archive.zip
+
+ If you are planning to build multiple versions of the plugins (for
+ different Eclipse releases for instance), you can run the setup and build
+ scripts from any directory, as long as you use the proper paths.
+
+ When switching between branches, you may need to run the setup.sh script
+ again to properly setup a different Eclipse environment. You may want to
+ change the "eclipse" symbolic link to point to the desired Eclipse
+ installation so that the already downloaded and installed files will be
+ recognized.
+
+
+III.2 Building Local Changes to Yocto Eclipse Plug-in
+
+ If you are building from a local branch, you should instead run:
+
+"ECLIPSE_HOME=<eclipse path> <path to>/scripts/build.sh -l <plugin branch or tag name> <documentation branch or tag name> <release name> 2>&1 | tee -a build.log"
+
+
+III.3 Install the Yocto Eclipse Plug-in
+
+ The file with the "-archive" in its name is the archive zip used for Eclipse
+ update manager (the "p2 repository"). The user can use the Eclipse update
+ manager to install it:
+ Help -> Install New Software... -> Add... -> Archive...
+ This is the recommended way to install the plugin during development.
+
+ The files without the "-archive" in their names are the zip containing
+ only the plugins/features. The user can unzip them into their target
+ eclipse "plugins" folder to install it.
+
+
+Part IV. Updating and Keeping Up-to-Date with Upstream Eclipse
+
+IV.1 Updating setup.sh script
+
+ When you would like to update the plugin to build for a new Eclipse release,
+ you need to make a few changes in the setup.sh script.
+
+ 1. If you are building for a non "Release" version of Eclipse, set the
+ appropriate value for "ep_rel", for instance "S-" for stable.
+
+ 2. Set "ep_ver" to the numeric version of the release, for instance "4.6"
+ for the original Neon release or "4.5.2" for the Mars.2 release or
+ "4.7M2" for the second Oxygen milestone.
+
+ 3. Set the "ep_date" to the date stamp on the tarball. The easiest way to
+ determine this is to go the main Eclipse website, click on the Downloads
+ button, click on the Download Packages link, click on the "Other builds"
+ link in the "More Downloads" sidebar and then hover over the version you
+ would like to download to see its fully qualified name. The "Other builds"
+ link currently resolves to http://download.eclipse.org/eclipse/downloads/
+ but this may change in the future.
+
+ 4. Set the MAIN_SITE to point to the desired release URL.
+
+ 5. Set the UPDATE_SITE to point to the correct update site for the release
+ in question. Note that for milestone releases (pre-release), the URL is
+ different since the numeric version has "milestones" appended to it (e.g.
+ "4.7milestones" for Oxygen pre-release).
+
+ 6. Set the versions of the various components to the desired version,
+ for instance CDTFEAT="9.0.0" for the original Neon release, but
+ became "9.1.0" for the Neon.1 release and will be "9.2.0" for the
+ upcoming Oxygen release.
+
+ 7. If any new components need to be added (new build dependencies), the
+ name of the feature must match exactly in order for the convenience
+ "update_feature_remote" function to work properly. A recommended way
+ to explore P2 repositories is included in the Oomph Setup SDK.
+ It can be found under "Window -> Show View -> Other... -> Oomph ->
+ Repository Explorer".
+
+
+IV.2 Staying Informed
+
+ Eclipse has either a major release or a point release approximately every
+ three months. At times, plugins and features may be moved to a different
+ update site. As an example, between the Mars release and the Mars.1 release,
+ the RSE plugin was officially deprecated and moved to a separate update site.
+
+ In order to stay on top of these changes, it is highly recommended that you
+ subscribe to at least the following mailing lists:
+
+ 1. C/C++ Development Tooling:
+ https://dev.eclipse.org/mailman/listinfo/cdt-dev
+
+ 2. Eclipse Packaging Project:
+ https://dev.eclipse.org/mailman/listinfo/epp-dev
+
+ 3. Cross Project Issues:
+ https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev
+
+ It is on these mailing lists that major API and ABI breaking changes will be
+ announced. As an example, the minimum required JDK version for Neon is 1.8.0,
+ which was announced on both the "EPP" and the "Cross Project" lists. These
+ mailing lists are also a place to discuss planned new features and commun-
+ icate with other Eclipse developers. It is not particularly time-consuming
+ to stay up to date, but if you wait for a year or two you might find that
+ upstream Eclipse has changed dramatically and it can be difficult to sync.
+
+
+Part V. Sharing with the Community
+
+V.1 Sending Patches to the Mailing List
+
+ Any changes to the eclipse-poky plugin should be sent as patches to
+ the Yocto Project mailing list (yocto at yoctoproject.org), with
+
+ --subject-prefix="eclipse-poky][PATCH"
+
+ This is a subscriber only list, so you will need to sign up for access at:
+
+ https://lists.yoctoproject.org/listinfo/yocto
+
+ Patches should follow the same guidelines that are used for other parts of
+ the Yocto Project and Open Embedded code-base:
+
+ http://www.openembedded.org/wiki/How_to_submit_a_patch_to_OpenEmbedded
+
+ Note that code included in the eclipse-poky plugin should be under the EPL
+ (Eclipse Public License) or a compatible license.
+
+V.2 Sharing Code in the eclipse-poky-contrib Repository
+
+ Similar to other -contrib repositories in the Yocto Project, there is
+ an eclipse-poky-contrib repository created for community members to be
+ able to share work-in-progress code or code for pull-requests.
+
+ http://git.yoctoproject.org/cgit/cgit.cgi/eclipse-poky-contrib/
+
+ To request access, follow the same instructions as for poky-contrib:
+
+ https://wiki.yoctoproject.org/wiki/Poky_Contributions#Request_Access
+
+
+Appendix A. Proxy Settings without Chameleonsocks
+
+A-1. using git through a SOCKS proxy(If you're behind some firewall)
+
+A-1.1 Create a wrapper script for netcat
+ cat > ~/bin/proxy-wrapper
+
+ #!/bin/sh
+ PROXY=proxy.example.com
+ PORT=8080
+ METHOD="-X 5 -x ${PROXY}:${PORT}"
+
+ nc $METHOD $*
+
+ Then Ctlr+D to save the file and "chmod +x ~/bin/proxy-wrapper"
+
+ Note: if netcat is not installed, please "sudo zypper install netcat-openbsd".
+
+A-1.2 set git proxy environment
+ add the following line to your ~/.bashrc and "source ~/.bashrc"
+
+ export GIT_PROXY_COMMAND="/somepath/bin/proxy-wrapper"
+
+ Please be noted that it should be absolute path, since "~" is not supported.
+
+A-2. using svn through a http_proxy(If you're behind some firewall)
+ Modify the ~/.subversion/servers
+
+ http-proxy-host = proxy.example.com
+ http-proxy-port = 8888
+
diff --git a/scripts/readme.txt b/scripts/readme.txt
deleted file mode 100644
index ba55b64..0000000
--- a/scripts/readme.txt
+++ /dev/null
@@ -1,71 +0,0 @@
-Note: PART I and PART II can be skipped if you have already done that.
-
-Part I: Base environment setup
-I-1. install JDK
- sudo zypper install java-1_6_0-openjdk
-
-I-2. install X11 related packages for eclipse running
- sudo zypper install xorg-x11-xauth
-
-I-3. using git through a SOCKS proxy(If you're behind some firewall)
-I-3.1 Create a wrapper script for netcat
- cat > ~/bin/proxy-wrapper
-
- #!/bin/sh
- PROXY=proxy-jf.intel.com
- PORT=1080
- METHOD="-X 5 -x ${PROXY}:${PORT}"
-
- nc $METHOD $*
-
- Then Ctlr+D to save the file and "chmod +x ~/bin/proxy-wrapper"
-
- Note: if netcat is not installed, please "sudo zypper install netcat-openbsd".
-
-I-3.2 set git proxy environment
- add the following line to your ~/.bashrc and "source ~/.bashrc"
-
- export GIT_PROXY_COMMAND="/somepath/bin/proxy-wrapper"
-
- Please be noted that it should be absolute path, since "~" is not supported.
-
-I-4. using svn through a http_proxy(If you're behind some firewall)
- Modify the ~/.subversion/servers
-
- http-proxy-host = proxy.jf.intel.com
- http-proxy-port = 911
-
-I-5. Get the scripts from eclipse-poky git
- git clone git://git.pokylinux.org/eclipse-poky.git
-
- The scripts used for auto builder is under the directory of "scripts".
-
-
-Part II: Setup the build environment
-II-1. Modify the scripts/setup.sh to set appropriate proxy settings.
- Set PROXY to a http proxy URL and PORT to the port number. Comment out
- these 2 variables if proxy is not required.
-
-II-2. Run scripts/setup.sh to set up the build environment.
- This will install the eclipse and relevant plugins required to build
- Yocto eclipse plug-in.
-
-Part III: Build & Install Yocto Eclipse plug-in
-
-To build the Yocto Eclipse plug-in, simply run
-"ECLIPSE_HOME=<eclipse path> scripts/build.sh <branch name> <release name>".
-
-The <eclipse install path> is the absolute path where you installed the
-eclipse in step II-2.
-
-The <branch name> is the git branch name you build based on.
-
-If successful, 2 files org.yocto.sdk-<release name>-<date>.zip and
-org.yocto.sdk.-<release name>-<date>-archive.zip will be genereated under the
-directory where you invoked the "build.sh" script.
-
-The file with the "-archive" in its name is the archive zip used for eclipse
-update manager. User should use eclipse update manager to install it.
-
-The file without the "-archive" in its name is the zip containing only the
-plugins/features. User should unzip it to the their target eclipse to install it.
--
2.7.4
More information about the yocto
mailing list