I want to put a configuration file in my Maven project. Looking at the standard directory layout, there are two places that seem sensible, "src/main/resources" and "src/main/config". Could someone explain the difference between these, and explain when you would put something in config and when in resources?
In this case, the file I'm looking at is ehcache.xml, but my question isn't ehcache specific, I'm curious for log4j.properties etc.
A bit of googling discovered this person had the same question, but the answers seemed contradictory, and not very authorative.
The email exchange at http://www.mail-archive.com/users#maven.apache.org/msg90985.html
says:
"This is all theory... Perhaps while writing the docs, someone involved with Maven development thought it might be useful to have a src/main/config directory and so it was included in docs, but since it was never implemented in the code, it is not being used today."
and
"The directory [src/main/config] doesn't show up on the classpath so the application or test classes
can't read anything in it."
So just use src/main/resources.
Note: I don't know if this is true (I'm the question asker), but that would explain why so many people on the web recommend src/main/resources for log4j.properties. If people agree this is the right answer could you let me know (comment or vote) I put it here to save other people the typing.
scr/main/resources is a place where you put your images, sounds, templates, language bundles, textual and binary files used by the source code. All config files like excache.xml, log4j.properties, logback.xml and others go to src/main/config.
Add to your pom.xml:
<build>
<resources>
<resource>
<targetPath>.</targetPath>
<directory>src/main/config</directory>
</resource>
</resources>
</build>
The inclusion of src/main/config in Maven's standard directory layout has been removed due in part to the confusion caused between src/main/config and src/main/resources. This very stackoverflow question is actually referenced in the JIRA ticket for the removal of src/main/config from Maven's standard.
Short answer: Use src/main/resources not src/main/config. It's the (new) Maven way.
Use case is pretty straightforward if you ask me. (It seems src/main/config has since been removed standard directory layout)
/src/main/resources go on into jar and thus on classpath
/src/main/config is intended for assembly plugin where you might construct a
zip file:
hello-world.zip
lib/
<dependencies>
bin/
run.bat
run.sh
config/
config.properies
Related
I'm trying to set up my first Ivy-powered build and am running into implementation problems, and I feel like I don't fully understand Ivy terminologies & best practices, even though I've spent a great deal of time reading the official docs and countless articles.
I have a SVN server that I want to use as the central repository for all of my projects. I do not want to use any public repositories! When I need a JAR, I'll pull it down from one of those public repos, run a checksum for security, and then push it to my SVN server (wherebyit will be deemed to be a "certified" version of the JAR; by certified, I really mean "safe").
(1) I want all of my projects to share the same ivy-settings.xml file. Do I put this in my SVN root, or somewhere inside SVN that makes sense? Here was my tentative thinking:
svn://MyRepoRoot/
ivy/
ivy-settings.xml
artifacts/
Project1/
trunk/
ivy.xml
...
branches/
tags/
Project2/
...
...
The ivy/ directory would contain a master copy of my ivy-settings.xml file. It would also contain an artifacts subdirectory where all of my "certified" JARs/WARs would go (as well as any publications my projects produce for downstream modules). Can I request for commentary?
(2) Also, something that I'm just not getting, is if each of my projects (modules) have their own ivy.xml file, and I want that file to reference the "global ivy-settings.xml file, which should by all means fall under its own, non-module-related versioning scheme, how do I pull down, say, Project1's trunk as my working copy, but configure it with the settings file which is not even a part of the same SVN project?!?
Thanks to anyone who can help give me a little practical advice and better clarity!
The ivysettings.xml is not referenced in the ivy.xml. You need the ivysettings.xml in your ant tasks to find the defined resolver, which resolve the artifacts defined in the ivy.xml.
ivy.xml defines the dependencies and ivysettings.xml the (local) runtime environment for ivy. You can change the ivysettings.xml anytime without need to edit the ivy.xml files.
The ivysettings.xml needs to be referenced in yout (ant) build.xml in ivys <settings /> task.
As for the layout. I use the same approach and it works fine for me.
I wrote my antfiles, so that I need to have the ivy folder checked out parallel to my project(s).
Another approach could be svns externals. But I never tried that.
If your svn has access over http you could also use the url parameter of the task to access ivysettings.xml.
I'm new to Maven and have skimmed over the documentation as I am following the Hibernate tutorial at http://docs.jboss.org/hibernate/stable/core/reference/en/html_single/#tutorial-firstapp-mvn.
I have installed Maven and successfully setup a web-app but this does not contain all of the standard directories mentioned in the tutorial. Am I going mad?
When building my Maven project I am using the maven-archetype-webapp. This gives me the arh-webapp\src\main\resources and arh-webapp\src\main\webapp directories but I'm missing quite a few directories mentioned on the link http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html.
Surely I don't have to manually add these? If not then the Hibernate documentation does not mention what archetype to use in order to achieve the directory structure used in their tutorial. Please can someone enlighten me.
What archetype do I need to use in order to have the above directory plus the src/main/java directory? If there is no such archetype then can easily append these using Maven? and how?
Surely you'll have to manually add these.
Just create those directories that according to the Maven convention are missing. Remember, a Maven Archetype is just a starting point to save you time configuring your workspace. After encountering many problems in some Archetypes myself I've been accustomed to just use a basic-web-app-archetype and then customize it myself, as a beginner with Maven you'll be better off doing that, and will learn a lot.
Regards.
Not all the directories mentioned are required for your standard web application. In fact, the reason behind the presence of the src/main/java, src/main/resources and the src/main/webapp directories is due to the archetype that you've used.
IMHO, the book titled "Better Builds with Maven" will serve you better; the Sonatype books on Maven might also help. The complete Maven documentation is also available as a PDF file, for future reference.
But just in case, you need some clarity on the terms used, here's some:
Archetype: A pattern for projects. Simple web applications (with no dependencies on other frameworks/libraries) have their own archetypes, so do applications using Spring, Hibernate, Seam, etc. Some archetypes will result in creation of different directories, as they are coded that way. You might be able to change the directory structures in most cases, although I cannot vouch for every archetype. For instance, it is quite possible to place your sources in 'src' instead of 'src/main/java', although this requires additional configuration in the POM.
Lifecycles, Phases and Goals: A Maven build lifecycle is a series of phases, with each phase executing a set of goals. Maven can be commanded to execute a build phase, which results in execution of all phases until and including the specified phase.
Maven plugins: Maven plugins contain one or more goals. Goals need not be bound to phases, but usually you would bind them to particular phases. Plugins are the basis for everything operational in Maven; you're using plugins even though you are just compiling the application (the Maven compiler plugin is a core plugin that is present in the Maven distribution).
I hope the above helps, but I would suggest that the reference books be followed.
I have to deal with what is pretty ugly and large blob of ColdFusion code which up to this day is maintained by direct modifications on production server (don't ask). I managed to clean it up from dupes and backups and put it into Subversion, now I need tp pick a make system to be able to put this onto continuous build (TeamCity) and also scheduled releases.
To my surprise I only found pretty much a single blog article on how to retrofit CF project with Maven, so the question is - does anyone have experience successfully using Maven on CF and what in general people use to manage large CF projects?
Your suggestions, tips and links will be much appreciated
Since I don't want to start religions wars - Maven is pretty much company standard (vs Ant)
First, here's another blog you might find helpful.
build-tools-maven-and-coldfusion
I haven't tried to build ColdFusion with Maven, but I have experience with managing Maven builds for a large company. There are a few things for you to consider.
Project structure
Coldfusion cfm and cfc files should be put in src/main/resources so they are bundled in the jar (the blog referenced above overrides the Maven convention to put them in src. this is ok, but could be a problem if you later need to add anything else to the project).
I'd probably keep cfc and cfm files in separate projects with appropriate dependency declarations to link them, this keeps your cfc projects as libraries and helps reuse. It is also worth considering the granularity of the cfc projects. Generally Maven's dependency management helps you keep artifacts small, with little need to worry about finding all the jars.
Deployment
The simplest way to deliver the artifacts is to use the maven-war-plugin to create a war containing your artifacts and all their transitive dependencies. This makes each application self-contained, which can be useful. The downside of this is that you'll end up bundling the same artifacts repeatedly and they can be quite large. To mitigate this you can either use the assembly-plugin to create custom packages excluding the common components, or you can specify that certain components (e.g. ColdSpring) are scope provided, this means they won't be included in the war.
Version Management
Maven encourages a proliferation of dependencies, by default each dependency declaration has a version, this can cause maintenance issues, particularly when you want to bump the version of an external dependency. You can mitigate this by defining a parent POM or an "app" POM. Either would have a dependencyManagement section declaring the details (groupId, artifactId, and version) for common artifacts. Any POM inheriting from the parent need not declare the dependency version as it will be inherited (note this doesn't mean that all children will have all dependencies, only that any that declare a dependency don't need to declare the version). If you define an "app" project with packaging "pom" and a dependencyManagement section, you can reference it with scope import (from Maven 2.0.9 onwards), this will import the dependencyManagement section from the "app" project to the project POM. See the dependency documentation for more details.
If you declare a dependency with a scope in the dependencyManagement section, that scope will be inherited unless it is overridden in the child POM. Related to the deployment section above, this means that you can declare the common libraries scope provided in the parent to ensure they are not bundled in each applciation.
Naming Conventions
You'll need a naming convention for the packages to avoid collisions.
It's probably best to follow the Maven convention and use java package-like groupIds (org.apache.maven for maven.apache.org) and the jar name for the artifact. This convention would give the groupId "org.coldspringframework" and artifactId "coldspring" for ColdSpring.
Further distinctions might need to be made across the company. For example, if you have a web and core team, you could give the web team the groupIds com.mycompany.web.* and the core team com.mycompany.core.*
Dependency Management
You'll need to add your CFC packages to a Maven repository such as Nexus so they are accessible to other builds across the enterprise.
If you want to keep the CFC packages separate to the jars. You can specify a custom packaging type, so that they won't be mixed up with any Java artifacts. If you create a custom packaging type, the artifacts can have the ".jar" extension, but any dependency declaration must have the type set.
Here's an example following those conventions:
<dependency>
<groupId>org.coldspringframework</groupId>
<artifactId>coldspring</artifactId>
<version>1.2</version>
<!--custom packaging type helps keep separate from Java artifacts-->
<type>cfc</type>
</dependency>
There's a section in the Nexus book that describes custom lifecycles (follow the links for more details. Essentially you need to create a plugin with a META-INf/plexus/components.xml to describe the plexus mechanics (what archiver to use, what extension to output etc).
The components.xml would look something like this:
<component-set>
<components>
<component>
<role>org.apache.maven.lifecycle.mapping.LifecycleMapping</role>
<role-hint>cfc</role-hint>
<implementation>org.apache.maven.lifecycle.mapping.DefaultLifecycleMapping</implementation>
<configuration>
<phases>
<process-resources>org.apache.maven.plugins:maven-resources-plugin:resources</process-resources>
<package>com.hsbc.maven.plugins:maven-jar-plugin:jar</package>
<install>org.apache.maven.plugins:maven-install-plugin:install</install>
<deploy>org.apache.maven.plugins:maven-deploy-plugin:deploy</deploy>
</phases>
</configuration>
</component>
<component>
<role>org.apache.maven.artifact.handler.ArtifactHandler</role>
<role-hint>cfc</role-hint>
<implementation>org.apache.maven.artifact.handler.DefaultArtifactHandler</implementation>
<configuration>
<extension>jar</extension>
<type>cfc</type>
<packaging>cfc</packaging>
</configuration>
</component>
<component>
<role>org.codehaus.plexus.archiver.Archiver</role>
<role-hint>cfc</role-hint>
<implementation>org.codehaus.plexus.archiver.zip.ZipArchiver</implementation>
<instantiation-strategy>per-lookup</instantiation-strategy>
</component>
<component>
<role>org.codehaus.plexus.archiver.UnArchiver</role>
<role-hint>cfc</role-hint>
<implementation>org.codehaus.plexus.archiver.zip.ZipUnArchiver</implementation>
<instantiation-strategy>per-lookup</instantiation-strategy>
</component>
</components>
</component-set>
Maven looked interesting to me too, but I couldn't find enough resources, and didn't have enough time to figure it out, so I moved onto what seemed to be good as well.
I understand you prefer to use Maven, I have come across several articles regarding Ant and Coldfusion, as well as a recent one about Hudson with Coldfusion.
Coldfusion also has the cfant (undocumented) tag. You can run ANT scripts right from CF?
I've asked a similar question in which part of this was addressed, but I'd like to expand in more detail.
When configuring maven to look at internal repositories, is it best to put that information in the project pom or in a user's settings.xml? An explanation on why would be really helpful here.
thanks,
Jeff
You should always try to make the maven project so that it compiles from a clean checkout from source control in your local environment; without a settings.xml. In my opinion this means that you place any overrides to sensible default values in the user's settings.xml file. But the pom should contain sensible values that will work for everyone.
I encourage you to put the repository definition in the POM, this way any developer just grab a copy of the code and run Maven to get it compiled, without having to change things in his settings file.
I find the setting.xml file useful just for hacking Maven's behaviour in special situations, for example when one repository is not accessible due to a firewall and you need to use a mirror. But that's my personal opinion. Maven documentation gives you more freedom:
The settings element in the
settings.xml file contains elements
used to define values which configure
Maven execution in various ways, like
the pom.xml, but should not be bundled
to any specific project, or
distributed to an audience. These
include values such as the local
repository location, alternate remote
repository servers, and authentication
information.
If you have a local repository which is used in every single project you may add that at the settings.xml, just be sure that configuration is well documented, in my current project it's not and new developers struggle at the beginning when they try to compile something.
We use the user's settings.xml and include info in the README about what possible other repos may be needed.
In theory a given group-artifact-version is the same no matter which repo it comes from. It works pretty well for us. If you find yourself with two different assets that have the same group-artifact-version identifier, then that indicates you're doing something really bad.
I'm just in the middle of revisiting maven. Our team had a bad experience when we last looked at this, as it was during the period when maven was rearchitecting from 1.x to 2.x, so a lot of the dependencies we needed hadn't been moved across to the new repositories. However, I have the time to reconsider now.
I am interested in using maven and either LaTeX or DocBook for creating documentation, and I was wondering if anyone had any experiences to share, project/module structure, good plugins to use, etc...
Many thanks :-)
Edit:
Just to clarify, I was looking to write a technical article/book, and my desired artifact would probably be a PDF.
DocBook is one of the many supported inputs to Doxia, the engine used to generate docs by maven. Refer here: http://maven.apache.org/doxia/modules/index.html
In fact, the Doxia site answers your exact question: http://maven.apache.org/doxia/book/index.html
You can easily create a site (that contains documentation) with Maven using the mvn site command (i.e. using the plugin site).
This plugin creates technical reports (such as Javadoc, Unit tests reports, code coverage...) but can be also used to create a "real site".
You have more details about that in this page.
Basically, you write your page using APT (Almost Plain Text which is quite simple to understand), or a XML-based format, Xdoc.
2 years ago, I create a complete user guide for one application I developed, using the XDoc format and the Site Maven plugin. Globally, it was quite easy to create!
I hope this will help you!
I've been using with success the Maven plugin Docbkx. You should give it a try
Docbkx
You should definitely take a look at the Maven Docbkx Plugin. It probably fits your needs. Doxia's support of DocBook is -uhm- suboptimal. In fact, last time I tried it, it generated something new that - as far as I could tell - wasn't DocBook.
The Maven Docbkx Plugin that I'm referring to supports all the customizations of the world (through plugin parameters, or XSLT overrides, if you're into that) + it features some mechanisms to integrate it with the Maven build. (Such as processing instructions for including Maven pom properties into your documents.)
Note that the ambition is to have a plugin that prevents you from having to manually put together a processing chain yourselves. So this plugin will both do the transformation to FO, and transforming that to PDF.
I recently implemented the project documentation for my maven multi-module project using docbook and the docbkx plugin for maven. I now have it automatically generating html and pdf files every time I build the project site. I think docbkx really rocks, so I would suggest you use that.
Its true -you can create a very nice site just using the maven site and doxia plugins. In fact I'm using those two to generate my project site, But doxia support for docbook is very limited and doesn't let you modularize documentation, including parts of documents in a main document, for instance. So for the big reference-manuals I'm using docbkx.
If you want to take a peek, my project is here. You can actually download the source and see the nitty gritty of it. And, of course, if you have any question regarding this setup, i'll be more than glad to help.
Cheers
Carlos
Although the question is quite old I want to give an update on this. If you want to use LaTeX for your documentation you should use a maven plugin to generate the documentation. There are a couple of maven-plugins doing this but a lot of them are not maintained anymore.
There is a new maven-plugin which requires none or less configuration to get it working and the generated PDF (or PS or DVI) can be published as artifact.
Have a look at: mathan-latex-maven-plugin
There is AFAIK no official or semi-official plugin that will process LaTeX or DocBook, but what you could do (besides using the aforementioned site plugin) is to configure the exec plugin to process your LaTeX/DocBook sources during the site lifecycle, i.e. at the same time that the project's website is built.
E.g., something like
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<executions>
<execution>
<id>latex</id>
<goals>
<goal>exec</goal>
</goals>
<phase>site</phase>
<configuration>
...
</configuration>
</execution>
</executions>
</plugin>