{"id":336,"date":"2015-06-16T12:59:12","date_gmt":"2015-06-16T02:59:12","guid":{"rendered":"http:\/\/www.docx4java.org\/blog\/?p=336"},"modified":"2015-09-04T13:15:19","modified_gmt":"2015-09-04T03:15:19","slug":"docx4j-from-github-in-eclipse-5-years-on","status":"publish","type":"post","link":"https:\/\/www.docx4java.org\/blog\/2015\/06\/docx4j-from-github-in-eclipse-5-years-on\/","title":{"rendered":"docx4j from GitHub in Eclipse &#8211; 3 years on"},"content":{"rendered":"<p>In May 2012 we posted\u00a0<a href=\"\/blog\/2012\/05\/docx4j-from-github-in-eclipse\/\">docx4j-from-github-in-eclipse<\/a>. That was more than 3 years ago now, so its about time to update that walkthrough \ud83d\ude42<\/p>\n<p>This post is about getting the docx4j source code setup in Eclipse, so you can not just use it, but easily study it as well (and submit pull requests!). \u00a0If you have no interest or need to do that, please see <a href=\"http:\/\/www.docx4java.org\/blog\/2011\/10\/hello-maven-central\/\">hello-maven-central<\/a> (if you&#8217;re already using a recent Eclipse, you can start at step 4) and\/or <a href=\"http:\/\/www.docx4java.org\/blog\/2013\/11\/docx4j-3-0-and-maven\/\">docx4j-3-0-and-maven<\/a> (but do use our current version 3.2.x)<\/p>\n<h2>Preliminaries &#8211; JDK<\/h2>\n<p>Make sure you have the JDK installed; Java 6 or later. \u00a0The JRE alone is not enough, since it doesn&#8217;t include a compiler (javac).<\/p>\n<h2>Preliminaries &#8211; Eclipse<\/h2>\n<p>Install Eclipse. \u00a0These days, the basic package has everything you need (ie git and maven support):<\/p>\n<p><a href=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/eclipse_download.jpg\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-339\" title=\"eclipse_download\" src=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/eclipse_download.jpg\" alt=\"\" width=\"484\" height=\"189\" srcset=\"https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/eclipse_download.jpg 484w, https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/eclipse_download-300x117.jpg 300w\" sizes=\"auto, (max-width: 484px) 100vw, 484px\" \/><\/a><\/p>\n<h2>Git &amp; GitHub<\/h2>\n<p>GitHub is docx4j&#8217;s authoritative source repository. \u00a0Eclipse now includes a git client. (If you have an older Eclipse, you can install eGit) However, it is still handy to have other git clients installed:<\/p>\n<ul>\n<li>on Linux (listed first, given git&#8217;s provenance), install git using your distribution&#8217;s package manager<\/li>\n<li>on Windows, the <a href=\"https:\/\/msysgit.github.io\/\">Git BASH shell<\/a> is handy; as is <a href=\"https:\/\/www.sourcetreeapp.com\/\">Atlassian&#8217;s SourceTree<\/a><\/li>\n<li>on OSX, ditto<\/li>\n<\/ul>\n<h2>Clone or Fork?<\/h2>\n<p>With Git, there is a difference between cloning and forking.<\/p>\n<ul>\n<li><strong>Cloning<\/strong> gives you a copy of the source code you can work on, but without more, no easy way to contribute changes back.<\/li>\n<li><strong>Forking<\/strong> sets you up with the source code, and makes it easy to contribute changes back.<\/li>\n<\/ul>\n<p>If you think you might be making changes to the docx4j source code, you\u2019re probably best to create a fork on GitHub right from the start.<\/p>\n<p>To create a fork, log in to GitHub, visit <a href=\"https:\/\/github.com\/plutext\/docx4j\">https:\/\/github.com\/plutext\/docx4j<\/a> then press the \u201cFork\u201d button.<\/p>\n<h2>Choose your poison<\/h2>\n<p>There are 3 steps to installing docx4j:<\/p>\n<ol>\n<li>clone the docx4j repo<\/li>\n<li>install its dependencies<\/li>\n<li>install docx4j project in Eclipse<\/li>\n<\/ol>\n<p>You can do these 3 steps entirely within Eclipse, but Eclipse by default doesn&#8217;t give much feedback as to what its doing, so you might wonder whether its still working properly.<\/p>\n<p>Since its just as easy (or easier) to use the command line, I&#8217;ll show that way first:-<\/p>\n<h2>Command Line Approach<\/h2>\n<p>To do it this way, you&#8217;ll need:<\/p>\n<ul>\n<li>a git shell, and<\/li>\n<li>Maven<\/li>\n<\/ul>\n<p>Both of these are worth having in any case.<\/p>\n<p><strong><span style=\"text-decoration: underline;\">Step 1.<\/span><\/strong> To clone docx4j from your git shell, use the github URL for docx4j (your fork or Plutext&#8217;s):<\/p>\n<p>$ <strong>git clone -b master &#8211;single-branch https:\/\/github.com\/plutext\/docx4j docx4j<\/strong><br \/>\nCloning into &#8216;docx4j&#8217;&#8230;<br \/>\nremote: Counting objects: 42008, done.<br \/>\nremote: Compressing objects: 100% (58\/58), done.<br \/>\nremote: Total 42008 (delta 23), reused 7 (delta 0), pack-reused 41946<br \/>\nReceiving objects: 100% (42008\/42008), 61.03 MiB | 128.00 KiB\/s, done.<br \/>\nResolving deltas: 100% (25108\/25108), done.<\/p>\n<p>You should now have a docx4j directory, containing the docx4j source code.<\/p>\n<p><strong><span style=\"text-decoration: underline;\">Step 2.<\/span><\/strong> Next, to get docx4j&#8217;s dependencies, you&#8217;ll need Maven.<\/p>\n<p>So first, install Maven (if you don&#8217;t have it already). \u00a0Please\u00a0<a href=\"http:\/\/maven.apache.org\/run-maven\/index.html\">see the instructions at maven.apache.org<\/a> (actually, you&#8217;ve already got Maven in Eclipse, but its a bit hard to use from the command line).<\/p>\n<p>Now you can go into your docx4j directory, and type:<\/p>\n<p><strong>mvn install -DskipTests=true<\/strong><\/p>\n<p>You&#8217;ll see Maven download docx4j&#8217;s dependencies.<\/p>\n<p><strong><span style=\"text-decoration: underline;\">Step 3.<\/span><\/strong> Now you are ready to start Eclipse.<\/p>\n<p>Because docx4j includes Eclipse project definition files, you can import the docx4j project.<\/p>\n<p>From the File menu, click Import, then Existing Projects into Workspace:<\/p>\n<p><a href=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/eclipse-file-import.jpg\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-346\" title=\"eclipse-file-import\" src=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/eclipse-file-import.jpg\" alt=\"\" width=\"328\" height=\"294\" srcset=\"https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/eclipse-file-import.jpg 328w, https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/eclipse-file-import-300x268.jpg 300w\" sizes=\"auto, (max-width: 328px) 100vw, 328px\" \/><\/a><\/p>\n<p>Browse to your docx4j directory:<\/p>\n<p><a href=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/eclipse-import-docx4j-short.png\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-351\" title=\"eclipse-import-docx4j-short\" src=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/eclipse-import-docx4j-short.png\" alt=\"\" width=\"618\" height=\"273\" srcset=\"https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/eclipse-import-docx4j-short.png 618w, https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/eclipse-import-docx4j-short-300x132.png 300w\" sizes=\"auto, (max-width: 618px) 100vw, 618px\" \/><\/a><\/p>\n<p>Then click Finish.<\/p>\n<p>Now the project should be set up correctly. \u00a0If you see errors, please refer further below for troubleshooting.<\/p>\n<h2>Eclipse only approach<\/h2>\n<p><strong><span style=\"text-decoration: underline;\">Step 1.<\/span> clone the docx4j git repo in Eclipse<\/strong>; for this you need the Git Repositories View:<\/p>\n<p>Window &gt; Show View &gt; Other &gt; Git &gt; Git Repositories View<\/p>\n<p><a href=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/repo_view.jpg\"><img loading=\"lazy\" decoding=\"async\" title=\"repo_view\" src=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/repo_view.jpg\" alt=\"\" width=\"323\" height=\"450\" \/><\/a><\/p>\n<p>Click &#8220;Clone a Git repository&#8221; then enter the URI for docx4j (your fork, or Plutext&#8217;s), then click Next.<\/p>\n<p><a href=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/clone_repo.jpg\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-338\" title=\"clone_repo\" src=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/clone_repo.jpg\" alt=\"\" width=\"817\" height=\"536\" srcset=\"https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/clone_repo.jpg 817w, https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/clone_repo-300x196.jpg 300w\" sizes=\"auto, (max-width: 817px) 100vw, 817px\" \/><\/a><\/p>\n<p>The master branch is probably all you need (though Eclipse will probably fetch all the others at some point anyway!)<\/p>\n<p><a href=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/choose_master.jpg\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-337\" title=\"choose_master\" src=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/choose_master.jpg\" alt=\"\" width=\"295\" height=\"426\" srcset=\"https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/choose_master.jpg 295w, https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/choose_master-207x300.jpg 207w\" sizes=\"auto, (max-width: 295px) 100vw, 295px\" \/><\/a><\/p>\n<p><strong><span style=\"text-decoration: underline;\">Step 2.<\/span><\/strong> On the next screen, you can tick &#8220;<strong>Import all existing projects after clone finishes<\/strong>&#8220;.\u00a0 (if you don&#8217;t do that, you&#8217;ll have to manually File &gt; Import, then Existing Projects into Workspace, as explained above)<\/p>\n<p><strong><span style=\"text-decoration: underline;\">Step 3.<\/span><\/strong> Eclipse will now start building the project; first Maven will get the dependencies.<\/p>\n<p>This may take a while &#8230; to see what Eclipse is doing while it displays the status &#8220;Building workspace&#8221;, from the Console view, click the drop down to see the Maven Console:<\/p>\n<p><a href=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/maven_console.png\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-340\" title=\"maven_console\" src=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/maven_console.png\" alt=\"\" width=\"595\" height=\"223\" srcset=\"https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/maven_console.png 595w, https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/maven_console-300x112.png 300w\" sizes=\"auto, (max-width: 595px) 100vw, 595px\" \/><\/a><\/p>\n<p>There you can watch it downloading stuff.<\/p>\n<p><a href=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/maven_downloads.jpg\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-341\" title=\"maven_downloads\" src=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/maven_downloads.jpg\" alt=\"\" width=\"995\" height=\"357\" srcset=\"https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/maven_downloads.jpg 995w, https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/maven_downloads-300x107.jpg 300w\" sizes=\"auto, (max-width: 995px) 100vw, 995px\" \/><\/a><\/p>\n<p>You can also look at the Progress view.<\/p>\n<p><a href=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/progress.jpg\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-342\" title=\"progress\" src=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/progress.jpg\" alt=\"\" width=\"1008\" height=\"191\" srcset=\"https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/progress.jpg 1008w, https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/progress-300x56.jpg 300w\" sizes=\"auto, (max-width: 1008px) 100vw, 1008px\" \/><\/a><\/p>\n<p>When its all done, you should have a docx4j project there and ready to go!<\/p>\n<h2>Troubleshooting<\/h2>\n<p>I don&#8217;t cover issues with git clone or maven here; just issues with Eclipse.<\/p>\n<p>If Eclipse has a problem with your docx4j project, you&#8217;ll see an exclamation mark:<\/p>\n<p><a href=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/project-error.png\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-353\" title=\"project-error\" src=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/project-error.png\" alt=\"\" width=\"196\" height=\"221\" \/><\/a><\/p>\n<p>You can see further info in the Problems view; the most likely problem is that your Java is misconfigured:-<\/p>\n<p><a href=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/problems-errors.png\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-352\" title=\"problems-errors\" src=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/problems-errors.png\" alt=\"\" width=\"669\" height=\"184\" srcset=\"https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/problems-errors.png 669w, https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/problems-errors-300x82.png 300w\" sizes=\"auto, (max-width: 669px) 100vw, 669px\" \/><\/a><\/p>\n<p>To fix this, on the docx4j project, click Alt-Enter to go into its properties.<\/p>\n<p>Then click Java Build Path, then the Libraries tab.<\/p>\n<p><a href=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/buildpath-libraries.png\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-350\" title=\"buildpath-libraries\" src=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/buildpath-libraries.png\" alt=\"\" width=\"810\" height=\"246\" srcset=\"https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/buildpath-libraries.png 810w, https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/buildpath-libraries-300x91.png 300w\" sizes=\"auto, (max-width: 810px) 100vw, 810px\" \/><\/a><\/p>\n<p>Do you see a red cross next to JRE System Library, as above?<\/p>\n<p>If so click on the JRE System Library entry to select it, then click the Remove button.<\/p>\n<p>Next click Add Library, the JRE System Library, then add one (1.6 or above).<\/p>\n<p><a href=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/compiler-compliance-level.png\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-355\" title=\"compiler compliance level\" src=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/compiler-compliance-level.png\" alt=\"\" width=\"809\" height=\"227\" srcset=\"https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/compiler-compliance-level.png 809w, https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/compiler-compliance-level-300x84.png 300w\" sizes=\"auto, (max-width: 809px) 100vw, 809px\" \/><\/a><\/p>\n<p>Note the warning:<\/p>\n<p><a href=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/warning-compliance.png\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-358\" title=\"warning-compliance\" src=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/warning-compliance.png\" alt=\"\" width=\"590\" height=\"73\" srcset=\"https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/warning-compliance.png 590w, https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/warning-compliance-300x37.png 300w\" sizes=\"auto, (max-width: 590px) 100vw, 590px\" \/><\/a><\/p>\n<p>That&#8217;s OK, we changed the JRE on the Java Build Path up above.<\/p>\n<h2>Hello World<\/h2>\n<p>Now you are ready to run some docx4j code.<\/p>\n<p><a href=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/samples-dir.png\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-361\" title=\"samples-dir\" src=\"http:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/samples-dir.png\" alt=\"\" width=\"373\" height=\"252\" srcset=\"https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/samples-dir.png 373w, https:\/\/www.docx4java.org\/blog\/wp-content\/uploads\/2015\/06\/samples-dir-300x202.png 300w\" sizes=\"auto, (max-width: 373px) 100vw, 373px\" \/><\/a><\/p>\n<p>A good place to start is to run\u00a0 <strong>CreateWordprocessingMLDocument<\/strong><\/p>\n<h2>Use docx4j in your own project<\/h2>\n<p>To use docx4j in your own project, there are 2 approaches:<\/p>\n<ul>\n<li>the <strong>Maven<\/strong> way. \u00a0If you&#8217;re planning to use Maven, you just specify docx4j as a dependency, and if the version matches (look in pom.xml), it&#8217;ll use your docx4j project (assuming workspace resolution is switched on). \u00a0Please see\u00a0<a href=\"http:\/\/www.docx4java.org\/blog\/2011\/10\/hello-maven-central\/\">hello-maven-central<\/a> (if you&#8217;re already using a recent Eclipse, you can start at step 4) and\/or\u00a0<a href=\"http:\/\/www.docx4java.org\/blog\/2013\/11\/docx4j-3-0-and-maven\/\">docx4j-3-0-and-maven<\/a> (but do use the version specified in pom.xml)<\/li>\n<li>or, via the Java Build Path &gt; Projects tab.<\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"<p>In May 2012 we posted\u00a0docx4j-from-github-in-eclipse. That was more than 3 years ago now, so its about time to update that walkthrough \ud83d\ude42 This post is about getting the docx4j source code setup in Eclipse, so you can not just use it, but easily study it as well (and submit pull requests!). \u00a0If you have no [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[92],"tags":[81,85,86,90],"class_list":["post-336","post","type-post","status-publish","format-standard","hentry","category-docx4j","tag-eclipse","tag-git","tag-github","tag-maven"],"_links":{"self":[{"href":"https:\/\/www.docx4java.org\/blog\/wp-json\/wp\/v2\/posts\/336","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.docx4java.org\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.docx4java.org\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.docx4java.org\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.docx4java.org\/blog\/wp-json\/wp\/v2\/comments?post=336"}],"version-history":[{"count":13,"href":"https:\/\/www.docx4java.org\/blog\/wp-json\/wp\/v2\/posts\/336\/revisions"}],"predecessor-version":[{"id":374,"href":"https:\/\/www.docx4java.org\/blog\/wp-json\/wp\/v2\/posts\/336\/revisions\/374"}],"wp:attachment":[{"href":"https:\/\/www.docx4java.org\/blog\/wp-json\/wp\/v2\/media?parent=336"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.docx4java.org\/blog\/wp-json\/wp\/v2\/categories?post=336"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.docx4java.org\/blog\/wp-json\/wp\/v2\/tags?post=336"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}