IG.GFX.Packager

Requirements

node.js (https://nodejs.org/en/download/) >= 16.19.0

Installation

1. Install this package globally. See "Migrating to ig.gfx.packager 3.0" if you've installed the packager locally previously

npm install -g @intelligentgraphics/ig.gfx.packager@latest

2. Add a build and a release command to the package.json

{
	"name": "a data repo",
	"scripts": {
		"build": "packager build",
		"upload": "packager publish",
		"postinstall": "packager postinstall"
	}
}

3. Configure a banner comment (this will be added to the output js files)

{
	"name": "a data repo",
	"scripts": {
		"build": "packager build",
		"upload": "packager publish",
		"postinstall": "packager postinstall"
	},
	"packager": {
		"banner": "This belongs to a data repo"
	}
}

Example final package.json

{
	"name": "IG.Graphics.Data.IGX",
	"version": "1.0.0",
	"private": true,
	"scripts": {
		"build": "packager build",
		"upload": "packager publish",
		"postinstall": "packager postinstall"
	},
	"packager": {
		"banner": "This file is part of the IG.Graphics IGX Data Package. \n Copyright (C) 2015 - 2020 intelligentgraphics. All Rights Reserved."
	}
}

Update

You can update the installed packager by running npm install -g @intelligentgraphics/ig.gfx.packager@latest again.

Environment configuration

This program requires the following environment variables to be set:

IG_GFX_ASSET_SERVICE

The service to which packages should be uploaded to.

Authentication

To use the new license file based authentication, the path to the license file needs to be provided in the IG_GFX_LICENSE environment variable. You can download your license file from the creator login page.

Alternatively the legacy username and password based authentication can be configured through the following environment variables:

IG_GFX_USER

The identifier of the user that will login at the IG_GFX_ASSET_SERVICE.

IG_GFX_PWD

The password for the user.

Usage

Building a package

This compiles the typescript of a single folder and moves the generated javascript and typescript declaration files into the bin folder.

npm run build Furniture

This command can also accept more than one folder name. When multiple folders are provided, they will be build in series.

npm run build Basics Furniture

A list of all possible options can be viewed by executing this command with the help option.

npm run build -- --help

Basics

When building a Basics package, this packager will also move the generated declaration file into the lib folder.

Build, package and upload a single package

This command builds a package, uploads it to the creator (IG.Asset.Server) and creates a zip file for release versions in the Releases folder.

The upload requires a newVersion option to be set with the target version.

npm run upload Furniture -- --newVersion=1.0.0.1

By default this command will upload the package to the sub domain specified in the _Package.json.

The target domain and sub domain may be overwritten by providing them as options to the command.

npm run upload Furniture -- --newVersion=1.0.0.1 --domain=TestDomain --subdomain=TestSubDomain

The upload can be prevented and debugged by specifying a noUpload option.

npm run upload Furniture -- --newVersion=1.0.0.1 --noUpload

This command also allows the address and service to be overwritten. A list of all possible options can be viewed by executing this command with the help option.

npm run upload -- --help

Using ig libraries

Installation

To use ig libraries like IG.GFX.Standard or IGX.Eval you need to install them as an npm package. They can be installed for the workspace either by manually adding them to the package.json of the workspace or by executing npm install {packagename}. Make sure to register a postinstall command in the workspace package.json, if it's not yet set, as shown in the installation examples.

The following packages can be installed:

@intelligentgraphics/3d.ig.gfx.core
@intelligentgraphics/3d.ig.math
@intelligentgraphics/3d.ig.gfx.standard
@intelligentgraphics/3d.ig.gfx.furniture
@intelligentgraphics/3d.igx.basic
@intelligentgraphics/3d.igx.bath
@intelligentgraphics/3d.igx.eval
@intelligentgraphics/3d.igx.furniture
@intelligentgraphics/3d.igx.geometry
@intelligentgraphics/3d.igx.meshcreator
@intelligentgraphics/3d.igx.upholstery

To install the package IG.GFX.Standard you can execute the command npm install @intelligentgraphics/3d.ig.gfx.standard.

Using the installed packages

In order to use the types of an installed package, a reference needs to be added to a typescript file of a package (generally an include.ts file). You can add a reference by including the following comment at the top of the file:

/// <reference types="@intelligentgraphics/3d.ig.gfx.standard" />

The packager also replaces the content of the legacy definition files within the lib folder with a reference to the installed definition files. The files are created when executing npm install or npm run postinstall. Old packages do not need to be updated to use these new dependencies.

Adding the required packages to the creator

After declaring these dependencies in the package.json, the ig.gfx.packager will automatically ensure the required packages are available for the target subdomain when uploading a package.

Migrating to ig.gfx.packager 3.0

The preferred installation method of the ig.gfx.packager has changed with version 3.0. The packager should now be installed as a global dependency once rather than as a local dependency for every single workspace.

The following steps are required to migrate to the new packager:

Install the packager globally by executing npm install -g @intelligentgraphics/ig.gfx.packager
Uninstall the packager by executing npm uninstall @intelligentgraphics/ig.gfx.packager in every workspace.

Migrating the build.txt

Previous versions of this packager only provided the option to build packages but not to upload them. With version 1.3.0, this program can also upload packages using a single command.

Build and publish of a package that is deployed to the domain specified in its _Package.json

For a package that is published to the same domain that is specified in the _Package.json, the build and upload can be updated as follows:

From

Release:
SET VERSION=1.0.0.100
Dev:
SET VERSION=1.0.0.1

npm run build Basics
$IG_GFX_PACKAGER -domain=IG -subdomain=Basics -version=$VERSION -service=$IG_GFX_ASSET_SERVICE -user=$IG_GFX_USER -password=$IG_GFX_PWD
%IG_GFX_PACKAGER% -domain=IG -subdomain=Basics -version=%VERSION% -service=%IG_GFX_ASSET_SERVICE% -user=%IG_GFX_USER% -password=%IG_GFX_PWD%

Dev:
npm run upload Basics --newVersion=1.0.0.1

Release:
npm run upload Basics --newVersion=1.0.0.100

Build and publish of a package that is deployed to a different domain than the one specified in its _Package.json

For a package that is published to a different domain than the one that is specified in the _Package.json, the build and upload can be updated as follows:

From

Release:
SET VERSION=1.0.0.100
Dev:
SET VERSION=1.0.0.1

npm run build Basics
$IG_GFX_PACKAGER -domain=IG -subdomain=Test -version=$VERSION -service=$IG_GFX_ASSET_SERVICE -user=$IG_GFX_USER -password=$IG_GFX_PWD
%IG_GFX_PACKAGER% -domain=IG -subdomain=Test -version=%VERSION% -service=%IG_GFX_ASSET_SERVICE% -user=%IG_GFX_USER% -password=%IG_GFX_PWD%

Dev:
npm run upload Basics -- --newVersion=1.0.0.1 --domain=IG --subdomain=Test

Release:
npm run upload Basics -- --newVersion=1.0.0.100 --domain=IG --subdomain=Test

Tsconfig

This program automatically creates a tsconfig file for every package to allow Visual Studio Code to provide the correct completions.

This tsconfig file includes the following options:

target

Sets the javascript version the typescript files should be compiled to.

lib

Specifies the standard libraries that are available.

Typedoc

The IG.GFX.Packager can automatically generate typedoc documentation for your typescript files.

This behaviour can be enabled by passing a --docs option when executing build or upload.

npm run upload Basics -- --newVersion=1.0.0.1 --domain=IG --subdomain=Test --docs

The typedoc files will be generated in a docs/ folder within the current directory.

Assets

The packager supports referencing assets from jsdoc comments which will be copied to the generated documentation.

An asset can be referenced using the following syntax:

class Test {
	/**
	 * <img src="media://image.png" alt="a png image"/>
	 */
}

The path specified after the media:// schema will be resolved within a directory called Media next to the _Package.json file.

_Index.json generation

The packager has a cli command npm run generateIndex [directory] to generate an _Index.json file for a scripting package.

You may need to register this command in the package.json of your git repository by adding the following attribute to the scripts object:

"scripts": {
   "generateIndex": "packager generateIndex"
},

This command collects all evaluator or interactor classes and generates an _Index.json file based on JSDoc informations for the properties of their parameters and the class itself.

In order for evaluator classes to be picked up, they need to either implement or extend the IEvaluator class from IGX.Eval. Interactor classes need to extend the IGX.Core.Interactor.

The following jsdoc attributes are supported:

default -> the default value
creatorType -> to define the type (like Material, String, Geometry)
summary -> to set a short description for the parameter. By default the generator will use the text above the attributes as the description.

Example:

namespace IG.Test {
	interface Params {
		/**
		 * Width of the corpus.
		 *
		 * Additional informations used to document the property internally
		 *
		 * @default 1.0
		 * @creatorType Float
		 * @summary Width of the corpus
		 */
		Corpus_Width?: number | string;

		/**
		 * Type of the corpus
		 *
		 * @default "extra_wide"
		 * @creatorType String
		 */
		Corpus_Type?: string;
	}

	/**
	 * The description of my evaluator
	 */
	export class MyEvaluator extends IGX.IEvaluator {
		public static Create(
			productId: string,
			path: string,
			parameters: Params,
		): IGX.EvalResponse {}
	}
}

The code snippet above will generate the following _Index.json output:

[
	{
		"Name": "IG.Test.MyEvaluator",
		"Description": "The description of my evaluator",
		"Type": "Evaluator",
		"Parameters": [
			{
				"Name": "Corpus_Width",
				"Description": "Width of the corpus",
				"Default": 1.0,
				"Type": "Float",
				"DisplayIndex": 1
			},
			{
				"Name": "Corpus_Type",
				"Description": "Type of the corpus",
				"Default": "extra_wide",
				"Type": "String",
				"DisplayIndex": 2
			}
		]
	}
]

Additionally when using the --strictOptional, this command will also mark non optional parameters as required.

Example for non optional parameters

namespace IG.Test {
	interface Params {
		/**
		 * Width of the corpus.
		 *
		 * Additional informations used to document the property internally
		 *
		 * @default 1.0
		 * @creatorType Float
		 * @summary Width of the corpus
		 */
		Corpus_Width: number | string;

		/**
		 * Type of the corpus
		 *
		 * @default "extra_wide"
		 * @creatorType String
		 */
		Corpus_Type: string;
	}

	/**
	 * The description of my evaluator
	 */
	export class MyEvaluator extends IGX.IEvaluator {
		public static Create(
			productId: string,
			path: string,
			parameters: Params,
		): IGX.EvalResponse {}
	}
}

The code snippet above will generate the following _Index.json output:

[
	{
		"Name": "IG.Test.MyEvaluator",
		"Description": "The description of my evaluator",
		"Type": "Evaluator",
		"Parameters": [
			{
				"Name": "Corpus_Width",
				"Description": "Width of the corpus",
				"Default": 1.0,
				"Type": "Float",
				"DisplayIndex": 1,
				"Required": true
			},
			{
				"Name": "Corpus_Type",
				"Description": "Type of the corpus",
				"Default": "extra_wide",
				"Type": "String",
				"DisplayIndex": 2,
				"Required": true
			}
		]
	}
]

The Required property will be used by the VSCode extension to show an error whenever a required parameter was not declared when configuring parameters for a script class.

Migrating from a handwritten _Index.json to an auto generated one:

Make sure all Evaluators implement or extend the IGX.IEvaluator class.
Run the index generation. The output should be nearly identical. If an evaluator does not have an explicit Parameter type, the generator will reuse the informations from an existing _Index.json file.
Now you can choose to add the parameter types either incrementally or all at once.

To aid with this migration you may also use the command packager generateParameterType [directory] [name] to generate a parameters interface for the class identified by the provided name using existing _Index.json informations. In order to generate a parameters interface for a class "AnimationInteractor" of the directory/package "Standard", you would execute the command packager generateParameterType Standard AnimationInteractor. This will generate txt file with the type next to the typescript files.

Troubleshoot

Definitions for ig libraries are not available even though they are registered as dependencies in the package.json

The definitions need to be installed by running npm install within the root folder of the git repository. Afterwards you may need to reload your editor in order for the installed files to be picked up.

History

IG.GFX.Packager 3.0.22

add some more logs
prevent double minify
fully support unminified js for release

IG.GFX.Packager 3.0.21

write source maps
add support for a watching build mode

IG.GFX.Packager 3.0.20

include images for ig.gfx.standard upload

IG.GFX.Packager 3.0.19

when parsing the package name as upload domain and sub domain, only use the first two parts that are separated by dots and ignore the rest -> IG.GFX.Standard -> Domain IG, SubDomain GFX

IG.GFX.Packager 3.0.18

add animation json schema to own files and no longer load it from archive

IG.GFX.Packager 3.0.17

use provided bin dir

IG.GFX.Packager 3.0.16

fix publishNpm for windows

IG.GFX.Packager 3.0.15

fall back to uploading files from memory if they can't be written to the file system

IG.GFX.Packager 3.0.14

remove $schema property from animations when adding them to js bundle

IG.GFX.Packager 3.0.13

update typescript and typedoc
refactor to bundle animations as part of build

IG.GFX.Packager 3.0.12

handle animation json ids that are not valid js identifiers
default creator index entry description to name
update typescript

IG.GFX.Packager 3.0.11

add library distribution
write version into _Package.json

IG.GFX.Packager 3.0.10

add strictOptional option for index generation -> see _Index.json generation

IG.GFX.Packager 3.0.9

exit with error code 1 on errors
sort generateIndex output alphabetically for root level entries

IG.GFX.Packager 3.0.8

allow typescript parameter type to be generated for _index.json entries
add support for interactors in _index.json generation

IG.GFX.Packager 3.0.7

correct readme example
update snapshot
fix inconsistency in default value handling for index generation

IG.GFX.Packager 3.0.6

fix check for local packager execution

IG.GFX.Packager 3.0.5

update documentation for generateIndex command
enforce better property order for parameters
improve index generation
use typechecker for index generation to improve reliability
reuse parameters of existing _index.json when no parameters are defined for an evaluator

IG.GFX.Packager 3.0.4

start a troubleshoot section
use platform line ending when writing definition files
wrap errors that occur when loading existing packages

IG.GFX.Packager 3.0.3

set explicit version for yargs
correct check for packages being available in both target and basics subdomain
prompt users to install 3d.ig.gfx.standard
change workspace package.json to be non optional

IG.GFX.Packager 3.0.2

handle folders in lib directory

IG.GFX.Packager 3.0.0

change packager to be installed globally (see Migrating to ig.gfx.packager 3.0)
offer to upload dependencies, that are defined in the workspace package json, to a creator sub domain if they are not available or outdated (see Using ig libraries)

IG.GFX.Packager 3.0.0-beta.3

fix build command
fix loading of localizations

IG.GFX.Packager 3.0.0-beta.2

remove json import

IG.GFX.Packager 3.0.0-beta.1

restructure to fix release on windows
preserve original module structure for output

IG.GFX.Packager 3.0.0-beta.0

update readme
ignore utf8 bom
improve readme
fix chunk file names handling to also work on windows

IG.GFX.Packager 3.0.0-alpha.9

change packager to be installed globally

IG.GFX.Packager 3.0.0-alpha.8

verify that packages are built in order when npm dependencies are defined
when multiple packages are requested to be built, first build basics if available
fix d.ts file references not being rewritten on build
use a narrower version range for node js
remove accidental packager postinstall

IG.GFX.Packager 3.0.0-alpha.7

fix some issues and update dependencies

IG.GFX.Packager 3.0.0-alpha.6

revert back to local installation

IG.GFX.Packager 3.0.0-alpha.5

also close asset server sessions in case of upload errors
do not check for required dependency versions if no dependencies exist
improve messages
ignore package.json when determining wether a repository is dirty

IG.GFX.Packager 3.0.0-alpha.4

fix pre release dependency version check

IG.GFX.Packager 3.0.0-alpha.3

fix source-map-support being inlined

IG.GFX.Packager 3.0.0-alpha.2

update to esm

IG.GFX.Packager 3.0.0-alpha.1

add missing shebang

IG.GFX.Packager 3.0.0-alpha.0

install globally instead of locally for every workspace
add support for dependency uploading
add support for library publishing

IG.GFX.Packager 2.3.4

add comment to the top of built js and d.ts files containing the version, commit sha and date

IG.GFX.Packager 2.3.3

support package names with multiple dots for animation json scopes

IG.GFX.Packager 2.3.2

reduce update check interval to 60 seconds

IG.GFX.Packager 2.3.1

fix scope not being created when only a version ts and animations exist

IG.GFX.Packager 2.3.0

handle additional white space in version log parsing
improve error message on invalid license path
add support for generation of index.json files for Evaluators

IG.GFX.Packager 2.2.0

add support for license files
improve error message when encountering invalid syntax in an animation json file

IG.GFX.Packager 2.1.4

support referencing assets from jsdoc for typedoc generation
update typescript and typedoc

IG.GFX.Packager 2.1.3

use package scope, if available, when adding animations

IG.GFX.Packager 2.1.2

improve handling of interactors with many dots in name
throw an error when executing build for a package without typescript files
migrate to jszip to resolve zip issues

IG.GFX.Packager 2.1.1

fix update notifier

IG.GFX.Packager 2.1.0

write "beta" or "patch" into version file for versions != x.x.x.100
remove client side version check
restrict typescript and typedoc version

IG.GFX.Packager 2.0.10

validate script runtime property
change schema validation to only log instead of refusing a file

IG.GFX.Packager 2.0.9

automatically generate a tsconfig when non exists

IG.GFX.Packager 2.0.8

also emit all diagnostics when emit wasn't skipped
fix release empty message
add message when no targets could be found for build or release

IG.GFX.Packager 2.0.7

fix copyright informations not being optional

IG.GFX.Packager 2.0.6

add noValidate option for publish
add pushOnly option for publish

IG.GFX.Packager 2.0.5

fix typo

IG.GFX.Packager 2.0.4

use postinstall rather than postprepare

IG.GFX.Packager 2.0.3

support generation of typedoc
fix releases path

IG.GFX.Packager 2.0.2

correct readme and description

IG.GFX.Packager 2.0.1

add postprepare script and update notifier

IG.GFX.Packager 2.0.0

version bump

IG.GFX.Packager 1.3.1

update readme
rename release to publish

IG.GFX.Packager 1.3.0

copy basics to lib folder
fix printing of comments
only archive actual releases
allow version to be set from env
reenable disabled modules
bump min node version to 10

IG.GFX.Packager 1.3.0-alpha.3

remove unnecessary inquirer prompts
copy basics to lib folder
fix printing of comments

IG.GFX.Packager 1.3.0-alpha.2

only archive actual releases

IG.GFX.Packager 1.3.0-alpha.1

fixes

IG.GFX.Packager 1.3.0-alpha.0

only allow a single directory for release
allow version to be set from env
reenable disabled modules
bump min node version to 10

IG.GFX.Packager 1.2.4

fixed node 6 support
added missing transpilation of js files

IG.GFX.Packager 1.2.3

added transpilation of dependencies. disabled release command

IG.GFX.Packager 1.2.2

changed target to node 6
added compilation with babel to ensure everything works on node 8

IG.GFX.Packager 1.2.1

IG.GFX.Packager 1.2.0

updated readme

IG.GFX.Packager 1.2.0-alpha.0

moved bridge settings validation
disabled index json reading
added maybe working net packager replacement

IG.GFX.Packager 1.1.3

added newVersion, targetDomain and targetSubdomain options

IG.GFX.Packager 1.1.2

IG.GFX.Packager 1.1.1

fixed releasing of packages with src folder

IG.GFX.Packager 1.1.0

[release] added noUpload option
[release] added using of default value for domains and subdomains when the input value is empty
[release] added ensuring that the new version is greater than the current version
[release] added overwriting of domain and subdomain via prompt

IG.GFX.Packager 1.1.0-alpha.5

fixed node polyfills...

IG.GFX.Packager 1.1.0-alpha.4

fixed locales not being published

IG.GFX.Packager 1.1.0-alpha.3

added localization

IG.GFX.Packager 1.1.0-alpha.2

rename to ig.gfx.packager
added overwriting of domain and subdomain via prompt for publish

IG.GFX.Packager 1.1.0-alpha.1

fixed release log format
added moving of built zip

IG.GFX.Packager 1.1.0-alpha.0

added remaining release functionality
release command initial commit

IG.GFX.Packager 1.0.4

added clean option

IG.GFX.Packager 3.0.16

@intelligentgraphics/ig.gfx.packager

IG.GFX.Packager

Requirements

Installation

Update

Environment configuration

IG_GFX_ASSET_SERVICE

Authentication

Usage

Building a package

Build, package and upload a single package

Using ig libraries

Migrating to ig.gfx.packager 3.0

Migrating the build.txt

Tsconfig

Typedoc

_Index.json generation

Troubleshoot

Definitions for ig libraries are not available even though they are registered as dependencies in the package.json

History

Readme

Keywords

Package Sidebar

Install

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

@intelligentgraphics/ig.gfx.packager

IG.GFX.Packager

Requirements

Installation

Update

Environment configuration

IG_GFX_ASSET_SERVICE

Authentication

Usage

Building a package

Build, package and upload a single package

Using ig libraries

Migrating to ig.gfx.packager 3.0

Migrating the build.txt

Tsconfig

Typedoc

_Index.json generation

Troubleshoot

Definitions for ig libraries are not available even though they are registered as dependencies in the package.json

History

Readme

Keywords

Package Sidebar

Install

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads