Commits

Jimmy Yuen Ho Wong committed 4e99e1b

Comments (0)

Files changed (1)

-== Welcome ==
-
-Welcome to your wiki! This is the default page we've installed for your convenience. Go ahead and edit it.
-
-=== Wiki features ===
-
-This wiki uses the [[http://www.wikicreole.org/|Creole]] syntax, and is fully compatible with the 1.0 specification.
-
-The wiki itself is actually a hg repository, which means you can clone it, edit it locally/offline, add images or any other file type, and push it back to us. It will be live immediately.
-
-Go ahead and try:
-
-{{{
-$ hg clone http://bitbucket.org/wyuenho/sbt-filter-plugin/wiki
-}}}
-
-Wiki pages are normal files, with the .wiki extension. You can edit them locally, as well as creating new ones.
-
-=== Syntax highlighting ===
-
-You can also highlight snippets of text, we use the excellent [[http://www.pygments.org/|Pygments]] library.
-
-Here's an example of some Python code:
-
-{{{
-#!python
-
-def wiki_rocks(text):
-	formatter = lambda t: "funky"+t
-	return formatter(text)
-}}}
-
-You can check out the source of this page to see how that's done, and make sure to bookmark [[http://pygments.org/docs/lexers/|the vast library of Pygment lexers]], we accept the 'short name' or the 'mimetype' of anything in there.
-
-Have fun!
+Copyright 2011 Yuen Ho Wong
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+== Motivation ==
+
+In the modern software development world, one will often have to deploy to a set of different environments during a project development lifecycle. A typical scenario would contain three sets of configurations - one for the development machine, one for the staging machine and finally one for the production machine - each is mostly the same as the others, but with slightly different settings such as a different database hostname, log file location etc. In Maven-land, one would handle it using [[http://maven.apache.org/pom.html#Profiles|profiles]] and [[http://maven.apache.org/guides/getting-started/index.html#How_do_I_filter_resource_files|filters]] like so:
+
+{{{
+#!xml
+
+<build>
+  <sourceDirectory>src/main/scala</sourceDirectory>
+  <testSourceDirectory>src/test/scala</testSourceDirectory>
+  <filters>
+    <filter>src/main/filters/dev.properties</filter>
+  </filters>
+  <resources>
+    <resource>
+      <directory>src/main/resources</directory>
+      <filtering>true</filtering>
+    </resource>
+  </resources>
+  <testResources>
+    <testResource>
+      <directory>src/test/resources</directory>
+      <filtering>true</filtering>
+    </testResource>
+  </testResources>
+  <plugins>
+    <plugin>
+      <groupId>org.apache.maven.plugins</groupId>
+      <artifactId>maven-war-plugin</artifactId>
+      <version>2.1</version>
+      <configuration>
+        <nonFilteredFileExtensions>
+          <nonFilteredFileExtension>ico</nonFilteredFileExtension>
+        </nonFilteredFileExtensions>
+        <webResources>
+          <resource>
+            <directory>src/main/webapp/META-INF</directory>
+            <targetPath>META-INF</targetPath>
+            <filtering>true</filtering>
+          </resource>
+        </webResources>
+      </configuration>
+    </plugin>
+  </plugins>
+  <profiles>
+    <profile>
+      <id>env-staging</id>
+      <activation>
+        <property>
+          <name>env</name>
+          <value>staging</value>
+        </property>
+      </activation>
+      <build>
+        <filters>
+          <filter>src/main/filters/staging.properties</filter>
+        </filters>
+      </build>
+    </profile>
+    <profile>
+      <id>env-prod</id>
+      <activation>
+        <property>
+          <name>env</name>
+          <value>prod</value>
+        </property>
+      </activation>
+      <build>
+        <filters>
+          <filter>src/main/filters/prod.properties</filter>
+        </filters>
+      </build>
+    </profile>
+  </profiles>
+}}}
+
+After this, one would tell Maven to use the appropriate profile like so:
+
+{{{
+#!bash
+
+$ mvn -Denv=prod package
+}}}
+
+This sure is a lot of cruft!
+
+**sbt-filter-plugin** aims to bring this functionality to projects using SBT, while maintaining compatibility with Maven's project structure, minus the XML verbosity and the command-line witchcraft.
+
+In order to use this plugin, put the following in your {{{project/plugins/Plugins.scala}}} file:
+
+{{{
+#!scala
+
+import sbt._
+class Plugins(info: ProjectInfo) extends PluginDefinition(info)
+{
+  val filterPlugin = "org.bitbucket" % "sbt_filter_plugin" % "1.0"
+}
+}}}
+
+And in your {{{project/build/Project.scala}}} file:
+
+{{{
+#!scala
+
+import sbt._
+import org.bitbucket.sbt_filter_plugin.SBTFilterPlugin
+class MyAwesomeProject(info: ProjectInfo) extends DefaultProject(info) with SBTFilterPlugin
+}}}
+
+Or, for .war projects:
+
+{{{
+#!scala
+
+import sbt._
+import org.bitbucket.sbt_filter_plugin.SBTWebappFilterPlugin
+class MyAwesomeProject(info: ProjectInfo) extends DefaultProject(info) with SBTWebappFilterPlugin
+}}}
+
+Now paramterize the resource files in your {{{src/main/resources/*}}}, {{{src/test/resources/*}}} and {{{src/main/webapp/**.xml}}} with {{{${some.parameter.key}}}} as usual.
+
+Instead of hard-coding the filter properties files to use in each profile, **sbt-filter-plugin** does something smarter. **sbt-filter-plugin** will automatically detect the properties files inside {{{src/main/filters}}} and make them available to you. The name of an environment is defined by the file name. For an environment named //prod//, one would put a properties file in {{{src/main/filters}}} named {{{prod.properties}}}. To select the environment to use, do the following:
+
+{{{
+#!bash
+
+$ sbt
+> set env prod
+}}}
+
+From now on every subsequent {{{sbt}}} resources action will use the values defined in {{{prod.properties}}} to filter the resource files.
+
+== Known Limitations ==
+
+* Currently **sbt-filter-plugin** does not filter any resource file under {{{src/main/webapp}}} other than //.xml// files. I may consider adding this functionality when there's a legitimate use-case.
+
+
+== Feedback and Bug Reports ==
+
+Go to the sbt-filter-plugin [[https://bitbucket.org/wyuenho/sbt-filter-plugin|project]] hosted on BitBucket.
+
+== Version History ==
+
+* 1.0 Initial Release