Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: added info on how to NOT build with mirage2 on

...

  • By default, DSpace does not build the Mirage 2 theme (as it lengthens the normal build process).  However, you can easily tell DSpace to build Mirage 2 by running the following from your [dspace-source] directory: 

    Code Block
    mvn package -Dmirage2.on=true

     

    • If you wish to speed up the Mirage 2 build process, you can do so by pre-installing all of the Mirage 2 dependencies on your system (by default they will be downloaded each time you rebuild Mirage 2).  This will significantly shorten the build process for Mirage 2.  More information on installing these prerequisites can be found in the Developer Documentation for Mirage 2.  Once these prerequisites have been installed on your local server, you can then build Mirage 2 more rapidly by running:

      Code Block
      # WARNING: This command will only work if you've manually installed *all* the prerequisites for Mirage 2
      mvn package -Dmirage2.on=true -Dmirage2.deps.included=false
    Warning

    Using an exclamation mark character ("!") in Maven directory name will cause a Mirage 2 build to fail. See:

    Jira
    serverDuraSpace JIRA
    serverIdc815ca92-fd23-34c2-8fe3-956808caf8c5
    keyDS-2749

  • After building Mirage 2, you can install this theme into your DSpace by simply re-running Ant from [dspace-source]/dspace/target/dspace-installer/ : 

    Code Block
    ant update


  • To enable Mirage 2, add the following to the <themes> section of your xmlui.xconf, replacing the currently active theme: 

    Code Block
    <theme name="Mirage 2" regex=".*" path="Mirage2/" />
  • Finally, restart your Tomcat or servlet container, and you should see the Mirage 2 theme.

NOT building with Mirage2

As you get used to building with the mirage2.on=true property, if you ever need to again build without the Mirage2 theme enabled (for example, if you wish to test functionality not associated with the Mirage2 theme), you might be tempted to "turn off" Mirage2 building by treating the mirage2.on property as a flag, and setting it to false. However, if you look at the Maven pom.xml files, you'll see that the value of the property is never checked, just the existence of it is important. If you wish to build without Mirage2, the easiest thing to do is to simply omit the mirage2.on property from your mvn command. If you'd really like to ensure the mirage2 profile is not used, you can explicitly disable the dspace-mirage2 profile with:

mvn package -P-dspace-xmlui-mirage2

Common Build Issues

  • Running the Mirage 2 build (mvn package -Dmirage.on=trueas the "root" user (or via sudo) will result in the following error from "Bower". This will result in a broken Mirage 2 build. The fix is to ensure you are building DSpace as a non-root user account. For more information on this Bower error, see: http://serverfault.com/questions/548537/cant-get-bower-working-bower-esudo-cannot-be-run-with-sudo

    Code Block
    bower ESUDO   Cannot be run with sudo
     
    Additional error details:
    Since bower is a user command, there is no need to execute it with superuser permissions.
  • The Mirage 2 build requires git. Ensure that git is installed before you launch the Mirage 2 build.
  • The Mirage 2 build process will attempt to retrieve some dependencies from GitHub via the "git" protocol. This requires outgoing access to github.com, port 9418. If the machine on which you're running the build has access restrictions in place for that port but outgoing access via HTTPS (port 443) is allowed, you can substitute the https protocol by running (with the same user account that will run the maven step):

    Code Block
    languagebash
    git config --global url."https://github.com/".insteadOf git://github.com/

    For more information on this issue, see

    Jira
    serverDuraSpace JIRA
    columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
    serverIdc815ca92-fd23-34c2-8fe3-956808caf8c5
    keyDS-2428

  • If you want to use the "quick build" option (where you run maven in [dspace-src]/dspace/), you must install the build dependencies locally, see
    Jira
    serverDuraSpace JIRA
    serverIdc815ca92-fd23-34c2-8fe3-956808caf8c5
    keyDS-2368
  • Maven 3.3.1 is not supported, see
    Jira
    serverDuraSpace JIRA
    serverIdc815ca92-fd23-34c2-8fe3-956808caf8c5
    keyDS-2533
  • If you are building on Windows, you may need extra quotes:

    Code Block
    languagebash
    mvn package '-Dmirage2.on=true'

...