gen-package-version 1.0.6
Generate a D module with version information automatically-detected from git/hg.
To use this package, run the following command in your project's root directory:
Manual usage
Put the following dependency into your project's dependences section:
gen-package-version
NOTE: If using together with DUB, you need DUB v1.0.0 or later. This project doesn't work with earlier versions of DUB due to this.
Automatically generate a D module with version and timestamp information (detected from git or Mercurial/hg) every time your program or library is built. You can also generate a DDOC macro file (using the `--ddoc=dir
` switch.)
Even better, all your in-between builds will automatically have their own VCS-generated version number, including the VCS commit hash (for example: `v1.2.0-1-g78f5cf9
`). So there's never any confusion as to which "version" of v1.2.0 you're running!
If detecting the version number via git/hg fails, gen-package-version will attempt to detect it via the currect directory name (ex, `~/.dub/packages/[project-name]-[version-tag]
`).
By default, gen-package-version will NOT re-generate the output files if the only difference is the build timestamp. So it won't trigger unnecessary rebuilds of your project.
[ Changelog ]
To Use:
It's recommended to use dub (get dub here). But if you wish, you can also forgo dub entirely (see the next section below).
First, add the following to your project's dub.sdl or dub.json:
dependency "gen-package-version" version="~>1.0.6"
preGenerateCommands "dub run gen-package-version -- your.package.name --root=$PACKAGE_DIR --src=path/to/src"
{
"dependencies": {
"gen-package-version": "~>1.0.6"
},
"preGenerateCommands":
["dub run gen-package-version -- your.package.name --root=$PACKAGE_DIR --src=path/to/src"]
}
Replace `path/to/src
with the path to your project's sources (most likely
src
or
source
`).
Replace `your.package.name
with the name of your project's D package (ex:
std
,
deimos
,
coolsoft.coolproduct.component1
`, etc...).
Optionally, you can replace `--src=path/to/src
with
--dub
. Then, gen-package-version will use dub (via
dub describe
`) to automatically detect your source path and add some extra info in the packageVersion module it generates. More options are also available (see "Help Screen" below).
Finally, make sure your project is tagged with a version number (if using git, it must be an "annotated" tag, ie a tag with a message - doesn't matter what the message is). Example:
$ git tag -a v1.2.0 -m 'Tag v1.2.0'
or
$ hg tag v1.2.0
That's it. Now your program will always be able to access its own version number (auto-detected from git) and build timestamp:
module your.package.name.main;
import std.stdio;
import your.package.name.packageVersion;
void main()
{
writeln("My Cool Program ", packageVersion);
writeln("Built on ", packageTimestamp);
// Only works of you used "--dub"
//writeln(`The "name" field in my dub.json is: `, packageName);
}
Every time you tag a new release (remember, annotated tag), your program will automatically know its new version number! Even builds from between releases will be easily distinguished.
If your project is a library, your library's users can also query the version of your lib:
module myApp.main;
import std.stdio;
import myApp.packageVersion;
static import coolLib.packageVersion;
void main()
{
writeln("My App ", packageVersion, "(@ ", packageTimestamp, ")");
writeln("Using coolLib ", coolLib.packageVersion.packageVersion);
writeln(" coolLib built @", coolLib.packageVersion.packageTimestamp);
}
By default, gen-package-version automatically adds the generated `packageVersion.d
file to your
.gitignore
(or creates it if you don't have one). This helps ensure the file's changes don't clutter your project's pull requests. If you'd rather gen-package-version left your
.gitignore
file alone, just include the
--no-ignore-file
` flag.
Your project isn't built with dub?
No prob! Just download and compile gen-package-version, then run it from your buildscript (or in your IDE's "Project Pre-Build Steps").
Download and compile using dub (get dub):
$ dub fetch gen-package-version
$ dub build gen-package-version
# Add this to your project's buildscript:
# dub run gen-package-version -- your.package.name --src=path/to/src
Or download and compile with no dub needed at all:
$ git clone https://github.com/Abscissa/gen-package-version.git
$ cd gen-package-version
$ git checkout v1.0.6 # Or newer
$ git clone https://github.com/Abscissa/scriptlike.git
$ cd scriptlike
$ git checkout v0.9.1 # Or newer
$ cd ..
$ rdmd --build-only -ofbin/gen-package-version -Isrc/ -Iscriptlike/src src/genPackageVersion/main.d
# Add this to your project's buildscript:
# [path/to/gen-package-version/]bin/gen-package-version your.package.name --src=path/to/src
Using as a library
Although support is very basic, gen-package-version can be used as a library instead of an executable:
In your `dub.sdl
or
dub.json
` (if using DUB):
dependency "gen-package-version" version="~>1.0.6"
subConfiguration "gen-package-version" "library"
"dependencies": {
"gen-package-version": "~>1.0.6"
},
"subConfigurations": {
"gen-package-version": "library"
}
In your source file:
import genPackageVersion.genAll;
import scriptlike.fail : Fail;
try {
// Just like running:
// gen-package-version foo.bar --src=source/dir
genPackageVersionMain(["dummy-exe-name", "foo.bar", "--src=source/dir"]);
}
catch(Fail e) {
// Do whatever.
//
// Or don't catch it at all to cleanly bail with appropriate
// output message and no ugly stack trace.
}
Or, you can bypass gen-package-version's commandline arg parsing and just set the flags directly in `genPackageVersion.util
. Then call
void genPackageVersion.genAll.generateAll(void)
. But unlike
genPackageVersionMain(args)
`, this approach is undocumented (unless you generate the docs with DDOC or DDOX yourself) and subject to change.
Help Screen
View this help screen with `dub run gen-package-version -- --help
or
gen-package-version --help
`:
gen-package-version v1.0.6
<https://github.com/Abscissa/gen-package-version>
-------------------------------------------------
Generates a D module with version information automatically-detected
from git or hg and (optionally) dub. This generated D file is automatically
added to .gitignore/.hgignore if necessary (unless using --no-ignore-file).
It is recommended to run this via DUB's preGenerateCommands by copy/pasting the
following lines into your project's dub.sdl (make sure to edit "path/to/src"
and "your.package.name" as needed):
dependency "gen-package-version" version="~>1.0.6"
preGenerateCommands \
"dub run gen-package-version -- your.package.name --root=$PACKAGE_DIR --src=path/to/src"
Or dub.json:
"dependencies": {
"gen-package-version": "~>1.0.6"
},
"preGenerateCommands":
["dub run gen-package-version -- your.package.name --root=$PACKAGE_DIR --src=path/to/src"]
USAGE:
gen-package-version [options] your.package.name --src=path/to/src
gen-package-version [options] your.package.name --dub
EXAMPLES:
gen-package-version foo.bar --src=source/dir
Generates module "foo.bar.packageVersion" in the file:
source/dir/foo/bar/packageVersion.d
Access the info from your program via:
import foo.bar.packageVersion;
writeln("Version: ", packageVersion);
writeln("Built on: ", packageTimestamp);
gen-package-version foo.bar --src=source/dir --ddoc=ddoc/dir
Same as above, but also generates a DDOC macro file:
ddoc/dir/packageVersion.ddoc
Which defines the macros: $(FOO_BAR_VERSION), $(FOO_BAR_TIMESTAMP)
and $(FOO_BAR_TIMESTAMP_ISO).
gen-package-version foo.bar --dub
Generates module "foo.bar.packageVersion" in the file:
(your_src_dir)/foo/bar/packageVersion.d
Where (your_src_dir) above is auto-detected via "dub describe".
The first path in "importPaths" is assumed to be (your_src_dir).
Additional info is available when using --dub:
writeln("This program's name is ", packageName);
Note that even if --dub isn't used, gen-package-version might still run dub
anyway if detecting the version through git/hg fails (for example, if the
package is not in a VCS-controlled working directory, such as the case when
a package is downloaded via dub).
OPTIONS:
--dub Use dub. May be slightly slower, but allows --src to be auto-detected, and adds extra info to the generated module.
-s --src = VALUE Path to source files. Required unless --dub is used.
-r --root = VALUE Path to root of project directory. Default: Current directory
--module = VALUE Override the module name. Default: packageVersion
--ddoc = VALUE Generate a DDOC macro file in the directory 'VALUE'.
--no-ignore-file Do not attempt to update .gitignore/.hgignore
--force Force overwriting the output file, even is it's up-to-date.
--dry-run Dry run. Don't actually write or modify any files. Implies --trace
-q --quiet Quiet mode
-v --verbose Verbose mode
--trace Extremely verbose mode (for debugging)
--version Show this program's version number and exit
-h --help This help information.
- 1.0.6 released 4 years ago
- Abscissa/gen-package-version
- github.com/Abscissa/gen-package-version
- zlib/libpng
- Authors:
- Dependencies:
- scriptlike
- Versions:
-
1.0.6 2020-May-13 1.0.5 2016-Sep-09 1.0.4 2016-Aug-23 1.0.3 2015-Aug-17 1.0.2 2015-Jul-01 - Download Stats:
-
-
0 downloads today
-
1 downloads this week
-
1 downloads this month
-
607 downloads total
-
- Score:
- 1.4
- Short URL:
- gen-package-version.dub.pm