Commits

Jimmy Yuen Ho Wong committed a56ee77

readme file

Comments (0)

Files changed (1)

+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 profiles [1]_ and filters [2]_ like so::
+
+  <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::
+
+  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::
+
+  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::
+
+  import sbt._
+  import org.bitbucket.sbt_filter_plugin.SBTFilterPlugin
+  class MyAwesomeProject(info: ProjectInfo) extends DefaultProject(info) with SBTFilterPlugin
+
+Or, for .war projects::
+
+  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::
+
+  $ 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 `project <https://bitbucket.org/wyuenho/sbt-filter-plugin>`_ hosted on BitBucket.
+
+Version History
+---------------
+
+- 1.0
+  Initial Release
+
+.. [1] http://maven.apache.org/pom.html#Profiles
+.. [2] http://maven.apache.org/guides/getting-started/index.html#How_do_I_filter_resource_files