From 06cae07c6391a54967ca245052a67a6b9a80cb5d Mon Sep 17 00:00:00 2001 From: Dave Syer Date: Thu, 12 May 2016 10:04:42 +0100 Subject: [PATCH] Re-org the building docs (lombok is not the default) --- .../asciidoc/building-base-no-lombok.adoc | 88 --------------- docs/src/main/asciidoc/building-base.adoc | 105 +++++++++++++----- docs/src/main/asciidoc/building-lombok.adoc | 33 ++++++ docs/src/main/asciidoc/building.adoc | 1 - 4 files changed, 111 insertions(+), 116 deletions(-) delete mode 100644 docs/src/main/asciidoc/building-base-no-lombok.adoc create mode 100644 docs/src/main/asciidoc/building-lombok.adoc diff --git a/docs/src/main/asciidoc/building-base-no-lombok.adoc b/docs/src/main/asciidoc/building-base-no-lombok.adoc deleted file mode 100644 index 651973b7..00000000 --- a/docs/src/main/asciidoc/building-base-no-lombok.adoc +++ /dev/null @@ -1,88 +0,0 @@ -=== Basic Compile and Test - -To build the source you will need to install JDK {jdkversion}. - -Spring Cloud uses Maven for most build-related activities, and you -should be able to get off the ground quite quickly by cloning the -project you are interested in and typing - ----- -$ ./mvnw install ----- - -NOTE: You can also install Maven (>=3.3.3) yourself and run the `mvn` command -in place of `./mvnw` in the examples below. If you do that you also -might need to add `-P spring` if your local Maven settings do not -contain repository declarations for spring pre-release artifacts. - -NOTE: Be aware that you might need to increase the amount of memory -available to Maven by setting a `MAVEN_OPTS` environment variable with -a value like `-Xmx512m -XX:MaxPermSize=128m`. We try to cover this in -the `.mvn` configuration, so if you find you have to do it to make a -build succeed, please raise a ticket to get the settings added to -source control. - -For hints on how to build the project look in `.travis.yml` if there -is one. There should be a "script" and maybe "install" command. Also -look at the "services" section to see if any services need to be -running locally (e.g. mongo or rabbit). Ignore the git-related bits -that you might find in "before_install" since they're related to setting git -credentials and you already have those. - -The projects that require middleware generally include a -`docker-compose.yml`, so consider using -http://compose.docker.io/[Docker Compose] to run the middeware servers -in Docker containers. See the README in the -https://github.com/spring-cloud-samples/scripts[scripts demo -repository] for specific instructions about the common cases of mongo, -rabbit and redis. - -NOTE: If all else fails, build with the command from `.travis.yml` (usually -`./mvnw install`). - -=== Documentation - -The spring-cloud-build module has a "docs" profile, and if you switch -that on it will try to build asciidoc sources from -`src/main/asciidoc`. As part of that process it will look for a -`README.adoc` and process it by loading all the includes, but not -parsing or rendering it, just copying it to `${main.basedir}` -(defaults to `${basedir}`, i.e. the root of the project). If there are -any changes in the README it will then show up after a Maven build as -a modified file in the correct place. Just commit it and push the change. - -=== Working with the code -If you don't have an IDE preference we would recommend that you use -http://www.springsource.com/developer/sts[Spring Tools Suite] or -http://eclipse.org[Eclipse] when working with the code. We use the -http://eclipse.org/m2e/[m2eclipe] eclipse plugin for maven support. Other IDEs and tools -should also work without issue. - -==== Importing into eclipse with m2eclipse -We recommend the http://eclipse.org/m2e/[m2eclipe] eclipse plugin when working with -eclipse. If you don't already have m2eclipse installed it is available from the "eclipse -marketplace". - -Unfortunately m2e does not yet support Maven 3.3, so once the projects -are imported into Eclipse you will also need to tell m2eclipse to use -the `.settings.xml` file for the projects. If you do not do this you -may see many different errors related to the POMs in the -projects. Open your Eclipse preferences, expand the Maven -preferences, and select User Settings. In the User Settings field -click Browse and navigate to the Spring Cloud project you imported -selecting the `.settings.xml` file in that project. Click Apply and -then OK to save the preference changes. - -NOTE: Alternatively you can copy the repository settings from https://github.com/spring-cloud/spring-cloud-build/blob/master/.settings.xml[`.settings.xml`] into your own `~/.m2/settings.xml`. - -==== Importing into eclipse without m2eclipse -If you prefer not to use m2eclipse you can generate eclipse project metadata using the -following command: - -[indent=0] ----- - $ ./mvnw eclipse:eclipse ----- - -The generated eclipse projects can be imported by selecting `import existing projects` -from the `file` menu. diff --git a/docs/src/main/asciidoc/building-base.adoc b/docs/src/main/asciidoc/building-base.adoc index bbc298e3..544335f5 100644 --- a/docs/src/main/asciidoc/building-base.adoc +++ b/docs/src/main/asciidoc/building-base.adoc @@ -1,35 +1,86 @@ -include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/building-base-no-lombok.adoc[] +=== Basic Compile and Test -==== Adding Project Lombok Agent +To build the source you will need to install JDK {jdkversion}. -Spring Cloud uses http://projectlombok.org/features/index.html[Project Lombok] -to generate getters and setters etc. Compiling from the command line this -shouldn't cause any problems, but in an IDE you need to add an agent -to the JVM. Full instructions can be found in the Lombok website. The -sign that you need to do this is a lot of compiler errors to do with -missing methods and fields, e.g. +Spring Cloud uses Maven for most build-related activities, and you +should be able to get off the ground quite quickly by cloning the +project you are interested in and typing + +---- +$ ./mvnw install +---- + +NOTE: You can also install Maven (>=3.3.3) yourself and run the `mvn` command +in place of `./mvnw` in the examples below. If you do that you also +might need to add `-P spring` if your local Maven settings do not +contain repository declarations for spring pre-release artifacts. + +NOTE: Be aware that you might need to increase the amount of memory +available to Maven by setting a `MAVEN_OPTS` environment variable with +a value like `-Xmx512m -XX:MaxPermSize=128m`. We try to cover this in +the `.mvn` configuration, so if you find you have to do it to make a +build succeed, please raise a ticket to get the settings added to +source control. + +For hints on how to build the project look in `.travis.yml` if there +is one. There should be a "script" and maybe "install" command. Also +look at the "services" section to see if any services need to be +running locally (e.g. mongo or rabbit). Ignore the git-related bits +that you might find in "before_install" since they're related to setting git +credentials and you already have those. + +The projects that require middleware generally include a +`docker-compose.yml`, so consider using +http://compose.docker.io/[Docker Compose] to run the middeware servers +in Docker containers. See the README in the +https://github.com/spring-cloud-samples/scripts[scripts demo +repository] for specific instructions about the common cases of mongo, +rabbit and redis. + +NOTE: If all else fails, build with the command from `.travis.yml` (usually +`./mvnw install`). + +=== Documentation + +The spring-cloud-build module has a "docs" profile, and if you switch +that on it will try to build asciidoc sources from +`src/main/asciidoc`. As part of that process it will look for a +`README.adoc` and process it by loading all the includes, but not +parsing or rendering it, just copying it to `${main.basedir}` +(defaults to `${basedir}`, i.e. the root of the project). If there are +any changes in the README it will then show up after a Maven build as +a modified file in the correct place. Just commit it and push the change. + +=== Working with the code +If you don't have an IDE preference we would recommend that you use +http://www.springsource.com/developer/sts[Spring Tools Suite] or +http://eclipse.org[Eclipse] when working with the code. We use the +http://eclipse.org/m2e/[m2eclipe] eclipse plugin for maven support. Other IDEs and tools +should also work without issue. + +==== Importing into eclipse with m2eclipse +We recommend the http://eclipse.org/m2e/[m2eclipe] eclipse plugin when working with +eclipse. If you don't already have m2eclipse installed it is available from the "eclipse +marketplace". + +NOTE: Older versions of m2e do not support Maven 3.3, so once the +projects are imported into Eclipse you will also need to tell +m2eclipse to use the `.settings.xml` file for the projects. If you +see many different errors related to the POMs in the projects, check +that you have an up to date installation. If you can't upgrade m2e, +add the "spring" profile to your `settings.xml`. Alternatively you can +copy the repository settings from the "spring" profile of the parent +pom. + +==== Importing into eclipse without m2eclipse +If you prefer not to use m2eclipse you can generate eclipse project metadata using the +following command: [indent=0] ---- -The method getInitialStatus() is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 120 Java Problem -The method getInitialStatus() is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 121 Java Problem -The method setNonSecurePort(int) is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 112 Java Problem -The type EurekaInstanceConfigBean.IdentifyingDataCenterInfo must implement the inherited abstract method DataCenterInfo.getName() EurekaInstanceConfigBean.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 131 Java Problem -The method getId() is undefined for the type ProxyRouteLocator.ProxyRouteSpec PreDecorationFilter.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/zuul/filters/pre line 60 Java Problem -The method getLocation() is undefined for the type ProxyRouteLocator.ProxyRouteSpec PreDecorationFilter.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/zuul/filters/pre line 55 Java Problem + $ ./mvnw eclipse:eclipse ---- -==== Importing into Intellij -Spring Cloud projects use annotation processing, particularly Lombok, which requires configuration -or you will encounter compile problems. It also needs a specific version of maven and a profile -enabled. Intellij 14.1+ requires some configuration to ensure these are setup properly. +The generated eclipse projects can be imported by selecting `import existing projects` +from the `file` menu. - 1. Click Preferences, Plugins. *Ensure Lombok is installed* - 2. Click New, Project from Existing Sources, choose your spring-cloud project directory - 3. Choose Maven, and select Environment Settings. *Ensure you are using Maven 3.3.3* - 4. In the next screen, *Select the profile `spring`* click Next until Finish. - 5. Click Preferences, "Build, Execution, Deployment", Compiler, Annotation Processors. *Click Enable Annotation Processing* - 6. Click Build, Rebuild Project, and you are ready to go! - -==== Importing into other IDEs -Maven is well supported by most Java IDEs. Refer to you vendor documentation. diff --git a/docs/src/main/asciidoc/building-lombok.adoc b/docs/src/main/asciidoc/building-lombok.adoc new file mode 100644 index 00000000..a06b6f9c --- /dev/null +++ b/docs/src/main/asciidoc/building-lombok.adoc @@ -0,0 +1,33 @@ +==== Adding Project Lombok Agent + +Spring Cloud uses http://projectlombok.org/features/index.html[Project Lombok] +to generate getters and setters etc. Compiling from the command line this +shouldn't cause any problems, but in an IDE you need to add an agent +to the JVM. Full instructions can be found in the Lombok website. The +sign that you need to do this is a lot of compiler errors to do with +missing methods and fields, e.g. + +[indent=0] +---- +The method getInitialStatus() is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 120 Java Problem +The method getInitialStatus() is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 121 Java Problem +The method setNonSecurePort(int) is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 112 Java Problem +The type EurekaInstanceConfigBean.IdentifyingDataCenterInfo must implement the inherited abstract method DataCenterInfo.getName() EurekaInstanceConfigBean.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 131 Java Problem +The method getId() is undefined for the type ProxyRouteLocator.ProxyRouteSpec PreDecorationFilter.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/zuul/filters/pre line 60 Java Problem +The method getLocation() is undefined for the type ProxyRouteLocator.ProxyRouteSpec PreDecorationFilter.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/zuul/filters/pre line 55 Java Problem +---- + +==== Importing into Intellij +Spring Cloud projects use annotation processing, particularly Lombok, which requires configuration +or you will encounter compile problems. It also needs a specific version of maven and a profile +enabled. Intellij 14.1+ requires some configuration to ensure these are setup properly. + + 1. Click Preferences, Plugins. *Ensure Lombok is installed* + 2. Click New, Project from Existing Sources, choose your spring-cloud project directory + 3. Choose Maven, and select Environment Settings. *Ensure you are using Maven 3.3.3* + 4. In the next screen, *Select the profile `spring`* click Next until Finish. + 5. Click Preferences, "Build, Execution, Deployment", Compiler, Annotation Processors. *Click Enable Annotation Processing* + 6. Click Build, Rebuild Project, and you are ready to go! + +==== Importing into other IDEs +Maven is well supported by most Java IDEs. Refer to you vendor documentation. diff --git a/docs/src/main/asciidoc/building.adoc b/docs/src/main/asciidoc/building.adoc index c8bd10d3..0375a590 100644 --- a/docs/src/main/asciidoc/building.adoc +++ b/docs/src/main/asciidoc/building.adoc @@ -1,4 +1,3 @@ :jdkversion: 1.7 include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/building-base.adoc[] -