development setup

[kendalldita]

For building and testing, I am using eclipse. I build dost.jar with gradle and copy it into src/main/lib so src/main can be used as dita.dir. Is there a better way?

[infotexture]

You shouldn't have to copy anything manually to use your repo clone as a functional toolkit.

1. In the root directory of your dita-ot repository, run Gradle to compile the Java code and install plugins:

   • On Linux, macOS, or Git Bash, use ./gradlew.
   • On Windows, use gradlew.bat.

2. Install any of the bundled plug-ins you need via dita install.

Then you should be able to use path/to/dita-ot/src/main/bin/dita just like the dita command from the released distribution builds.

[chrispy-snps]

One thing that confused me at first is that the source-based DITA-OT in src/main/ is only the core DITA-OT functionality. The public DITA-OT distribution includes additional plugins that come from external repositories rather than being in the core DITA-OT repository.

To build a DITA-OT distribution image that includes these extra plugins, run ./gradlew dist. When it completes, you will have two DITA-OTs in your repository:

src/main/bin/dita
build/tmp/dist/bin/dita

The first is the core functionality only, and the second is the full distribution. For example,

$ src/main/bin/dita transtypes
html5
xhtml
htmlhelp
pdf
pdf2

$ build/tmp/dist/bin/dita transtypes
pdf
xhtml
eclipsehelp
html5
htmlhelp
dita
pdf2
markdown
markdown_github
markdown_gitbook

I use the source-based DITA-OT when I can because debug iteration is quick. However, some problems require the full distribution to debug. For example, when debugging issue #4337 for <index-see-also>, I found that that functionality is in the external org.dita.index plugin, so I had to use the distribution image to debug it.

[infotexture]

That's also correct. The distribution build installs the bundled plug-ins from the list in Step 2 above:

2. Install any of the bundled plug-ins you need via dita install.

If you only need one of those, you can install it separately. If you need them all, run ./gradlew dist.

See also: Use a fresh worktree for distribution builds.

[chrispy-snps]

@infotexture - are you saying that I could install individual plugins in the source installation:

$ ./src/main/bin/dita \
    install https://github.com/dita-ot/org.dita.index/releases/download/1.0.0/org.dita.index-1.0.0.zip
Added org.dita.index

and this is okay and it won't interfere with any subsequent unit testing or distribution builds?

[infotexture]

That's how I test. You need to remember to update any plugins you install this way, as they won't be updated just by pulling & running the Gradle build, but the advantage is you can also test this way with newer plugin versions that aren't yet included in the build.

Anything you install this way will show up in Git as new, but you can add the directories to $GIT_DIR/info/exclude so Git won't notice.

Here's what (this part of) my local exclude file looks like:

# Ignore entries for 'bundled' external plugins per `build.gradle`
# https://github.com/dita-ot/dita-ot/blob/develop/build.gradle#L206-L217
# These are installed into distribution builds when `gradle dist` runs, but no longer included in the repo
# For local use with `src/main/bin/dita`, each must be installed with `dita install`:
src/main/plugins/com.elovirta.pdf
src/main/plugins/org.dita.eclipsehelp
src/main/plugins/org.dita.index
src/main/plugins/org.dita.normalize
src/main/plugins/org.dita.pdf2.axf
src/main/plugins/org.dita.pdf2.xep
src/main/plugins/org.dita.specialization.dita11
src/main/plugins/org.lwdita
src/main/plugins/org.oasis-open.dita.techcomm.v2_0
src/main/plugins/org.oasis-open.dita.v1_2
src/main/plugins/org.oasis-open.dita.v2_0
src/main/plugins/org.oasis-open.xdita.*

If I ever need to rule out peculiarities stemming from my local setup, I just use a fresh worktree for distribution builds.

I assume @jelovirt probably uses a similar approach.

[kendalldita]

Very late accepting the answer. Thanks.

[kendalldita]

In eclipse, for example, run/debug configurations find dost.jar in bin/... until ant is invoked, then it finds the jar in lib/, so I copy the jar into lib after builds, otherwise changes aren't found.