Skip to content

Latest commit

 

History

History
193 lines (149 loc) · 12.1 KB

README.adoc

File metadata and controls

193 lines (149 loc) · 12.1 KB
Raw
Build Status

autoln

The autoln command keeps generational symbolic links to a project’s docs and/or schemas to be kept up to date. For example, if the latest build of Spring Framework is 5.2.9.RELEASE it makes it easier for users to refer to the docs using a symlink of current and 5.2.x. When the Spring 5.2.9.RELEASE release is performed, the autoln command can ensure the links are automatically updated so users do not need to update bookmarks.

autoln generated links

Below is a list of supported symbolic links that are generated when using autoln. The links can be enabled for a project’s docs and/or schema.

  • current the latest stable build. This is defined as the largest version number ending in .RELEASE or ending in a number.

  • current-SNAPSHOT the most recent snapshot. This is defined as the largest version number ending in CI-SNAPSHOT, BUILD-SNAPSHOT, or -SNAPSHOT.

  • <major>.<minor>.x the most recently released version starting with <major>.<minor>. This reference can refer to a milestone build (in the event there are no builds that end in .RELEASE or a number), but will not refer to a snapshot. For example, to get the most recently released version of 5.2, one could use the link 5.2.x.

  • <major>.<minor>.x-SNAPSHOT the most recent snapshot starting with <major>.<minor>. For example, to get the most recently snapshot of 5.2, one could use the link 5.2.x-SNAPSHOT.

If a project uses a different naming convention, then a one-time link pointing to the links updated by the autorepo script can be created. For example, if the project uses ga instead of current, a link named ga pointing to current could be created.

subcommands

autoln supports two subcommands

print

autoln-print - Use to print out the symlinks that would be created by the autoln command.

autoln print [-hV] (--project-dir=<projectDir> | (--scan-dir=<scanDir> [--maxdepth=<maxDepth>]))

-h, --help

Show this help message and exit.

--maxdepth=<maxDepth>

the maxdepth levels of a directories to scan when using scan-dir option

--project-dir=<projectDir>

The directory that should be processed. No marker file is necessary

--scan-dir=<scanDir>

Indicates that each subdirectory of the scanDir that contains .autoln-scan should be processed as a project-dir

-V, --version

Print version information and exit.

Before using autoln to create your links, it is a good idea to print out the links it will create. This can be done using the print sub-command with the --project-dir argument. For example, this would print out the links that would be created for the spring-security project:

autoln print --project-dir="/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security"

Symlinks for project at '/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security'
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/2.0.x => 2.0.8.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/3.0.x => 3.0.8.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/3.0.x-SNAPSHOT => 3.0.9.CI-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/3.1.x => 3.1.7.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/3.1.x-SNAPSHOT => 3.1.8.CI-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/3.2.x => 3.2.10.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/3.2.x-SNAPSHOT => 3.2.11.BUILD-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/4.0.x => 4.0.4.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/4.0.x-SNAPSHOT => 4.0.5.CI-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/4.1.x => 4.1.5.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/4.1.x-SNAPSHOT => 4.1.6.BUILD-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/4.2.x-SNAPSHOT => 4.2.19.BUILD-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/4.2.x => 4.2.19.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.0.x => 5.0.19.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.0.x-SNAPSHOT => 5.0.20.BUILD-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.1.x => 5.1.13.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.1.x-SNAPSHOT => 5.1.14.BUILD-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.2.x => 5.2.7.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.2.x-SNAPSHOT => 5.2.8.BUILD-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.3.x => 5.3.5.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.3.x-SNAPSHOT => 5.3.6.BUILD-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.4.x => 5.4.1
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.4.x-SNAPSHOT => 5.4.2-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.5.x-SNAPSHOT => 5.5.0-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/current => 5.4.1
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/current-SNAPSHOT => 5.5.0-SNAPSHOT

By using the --project-dir argument, we instruct autoln to use the directory we specified to search for symlinks to create.

Instead of --project-dir the autoln command can specify --scan-dir which will process every subdirectory it finds with a marker file named .autoln-scan as a project-dir. This is useful since piping the results to autoln --project-dir would create a new Java process (which is slow) for each project that was found. To further speed things up , the --scan-dir argument is typically accompanied by the --maxdepth argument which specifies how deep to search for the .autoln-scan marker files. An example can be found below:

autoln print --scan-dir="/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/" --maxdepth=2


Symlinks for project at '/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security'
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/2.0.x => 2.0.8.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/3.0.x => 3.0.8.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/3.0.x-SNAPSHOT => 3.0.9.CI-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/3.1.x => 3.1.7.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/3.1.x-SNAPSHOT => 3.1.8.CI-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/3.2.x => 3.2.10.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/3.2.x-SNAPSHOT => 3.2.11.BUILD-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/4.0.x => 4.0.4.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/4.0.x-SNAPSHOT => 4.0.5.CI-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/4.1.x => 4.1.5.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/4.1.x-SNAPSHOT => 4.1.6.BUILD-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/4.2.x-SNAPSHOT => 4.2.19.BUILD-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/4.2.x => 4.2.19.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.0.x => 5.0.19.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.0.x-SNAPSHOT => 5.0.20.BUILD-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.1.x => 5.1.13.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.1.x-SNAPSHOT => 5.1.14.BUILD-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.2.x => 5.2.7.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.2.x-SNAPSHOT => 5.2.8.BUILD-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.3.x => 5.3.5.RELEASE
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.3.x-SNAPSHOT => 5.3.6.BUILD-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.4.x => 5.4.1
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.4.x-SNAPSHOT => 5.4.2-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/5.5.x-SNAPSHOT => 5.5.0-SNAPSHOT
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/current => 5.4.1
/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security/current-SNAPSHOT => 5.5.0-SNAPSHOT

... other projects with .autoln-scan in them below ...

create

autoln-create - use to create symlinks for each generation

autoln create [-hV] (--project-dir=<projectDir> | (--scan-dir=<scanDir> [--maxdepth=<maxDepth>]))

-h, --help

Show this help message and exit.

--maxdepth=<maxDepth>

the maxdepth levels of a directories to scan when using scan-dir option

--project-dir=<projectDir>

The directory that should be processed. No marker file is necessary

--scan-dir=<scanDir>

Indicates that each subdirectory of the scanDir that contains .autoln-scan should be processed as a project-dir

-V, --version

Print version information and exit.

Once you have printed the links to verify they are what you want, you can then use autoln to create your links. This can be done using the create sub-command with the --project-dir argument. For example, this would create the links that would be created for the spring-security project:

Creating Symlinks for project at '/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security'
$ ls -alt /opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security
total 24
Oct 13 18:52 .
14 Oct 13 18:52 5.5.x-SNAPSHOT -> 5.5.0-SNAPSHOT
5 Oct 13 18:52 current -> 5.4.1
14 Oct 13 18:52 current-SNAPSHOT -> 5.5.0-SNAPSHOT
20 Oct 13 18:52 5.3.x-SNAPSHOT -> 5.3.6.BUILD-SNAPSHOT
5 Oct 13 18:52 5.4.x -> 5.4.1
...

By using the --project-dir argument, we instruct autoln to use the directory we specified to search for symlinks to create.

Instead of --project-dir the autoln command can specify --scan-dir which will process every subdirectory it finds with a marker file named .autoln-scan as a project-dir. This is useful since piping the results to autoln --project-dir would create a new Java process (which is slow) for each project that was found. To further speed things up , the --scan-dir argument is typically accompanied by the --maxdepth argument which specifies how deep to search for the .autoln-scan marker files. An example can be found below:

autoln create --scan-dir="/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/" --maxdepth=2

Creating Symlinks for project at '/opt/www/domains/spring.io/docs/htdocs/autorepo/docs/spring-security'

... other projects with .autoln-scan in them below ...

The Spring docs server has a chron job that runs the command above every 20 minutes. This means if a project is in the autorepo directory and includes the .autoln-scan marker file in its root directory, its symlinks will automatically be updated.

Supplemental

It is possible to add supplemental files to the symlinks by creating a sibling directory that contains the supplemental content that has the same name as the symlink but prefixed with a .. For example, to have supplemental content for the symlink current create a sibbling directory named .current that should have the supplemental content in it. Each file within .current will be linked to within current so as to avoid overriding anything except what is explicitly in the supplemental files.