1 | <p align="center">
|
2 | <img src="https://kenticoprod.azureedge.net/kenticoblob/crestron/media/crestron/generalsiteimages/crestron-logo.png">
|
3 | </p>
|
4 |
|
5 | # CH5 Utilities - Getting Started
|
6 |
|
7 | > Archiving and distribution utilities to be used by the applications implemented with the CH5 Components Library.
|
8 |
|
9 | ## Table of Contents
|
10 |
|
11 | - [Background](#background)
|
12 | - [Setup](#setup)
|
13 | - [Commands](#commands)
|
14 | - [Configuration](#configuration)
|
15 | - [License](#license)
|
16 |
|
17 | ## Background
|
18 |
|
19 | The purpose of the library is to satisfy three functions:
|
20 |
|
21 | - archiving - create a package that can distributed manually or with the utility
|
22 | - distribution - deploy a package built with the utility
|
23 | - archive & distribute - single command for both of the above
|
24 |
|
25 | The final result of the archiving will be a .ch5z package.
|
26 | This contains two files:
|
27 |
|
28 | - *.ch5 - the actual package
|
29 | - *_manifest.json - a manifest file describing the .ch5 file ( project name, timestamp, hash and any other optional details)
|
30 |
|
31 | ## Setup
|
32 |
|
33 | Install the required packages.
|
34 | ```
|
35 | yarn install
|
36 | ```
|
37 |
|
38 | Build the library.
|
39 | ```
|
40 | yarn build
|
41 | ```
|
42 |
|
43 | Publish the ch5-utilities library for local usage.
|
44 | ```
|
45 | yarn link
|
46 | ```
|
47 |
|
48 | ## Commands
|
49 |
|
50 | The commands is for development, debugging, and testing purposes only.
|
51 |
|
52 | Before running, make sure that all the values are properly modified for local usage, in the `config` variable in `start.ts`.
|
53 |
|
54 | #### yarn start
|
55 |
|
56 | Running `yarn start` will run the **archive&deploy** functions based on the config in the `src/start.ts` file.
|
57 |
|
58 | #### yarn start:archive
|
59 |
|
60 | Running `yarn start:archive` will run the **archive** function based on the config in the `src/start.ts` file.
|
61 |
|
62 | #### yarn start:distribute
|
63 |
|
64 | Running `yarn start:distribute` will run the **distribute** function based on the config in the `src/start.ts` file.
|
65 |
|
66 | #### yarn start:js
|
67 |
|
68 | Same as `yarn start`, but will run the bundled JS version of the library ( the one in the ``build`` directory ).
|
69 |
|
70 | #### yarn start:js:archive
|
71 |
|
72 | Same as `yarn start:archive`, but will run the bundled JS version of the library ( the one in the ``build`` directory ).
|
73 |
|
74 | #### yarn start:js:distribute
|
75 |
|
76 | Same as `yarn start:distribute`, but will run the bundled JS version of the library ( the one in the ``build`` directory ).
|
77 |
|
78 | #### yarn publish:local
|
79 |
|
80 | After the initial setup, you can use this command to rebuild and publish changes in the library.
|
81 |
|
82 | ## Configuration
|
83 |
|
84 | The methods `archiver` and `distributor` from `src/index.ts` expect a to get a configuration of type `IConfigOptions`.
|
85 |
|
86 | Below we describe each property, their purpose and possible values.
|
87 |
|
88 | #### projectName
|
89 |
|
90 | Required.
|
91 |
|
92 | The name of the project will set the package name and the manifest details for the project.
|
93 | It should be set according to the delivered package.
|
94 |
|
95 | Default value is ``crestron-system``.
|
96 |
|
97 | #### directoryName
|
98 |
|
99 | Required.
|
100 |
|
101 | This is the path to the directory that contains the deliverables.
|
102 |
|
103 | Currently this is the showcase-app dist directory.
|
104 |
|
105 | The path can be absolute or should be relative to the location from which the command is run in the CLI.
|
106 |
|
107 | #### outputDirectory
|
108 |
|
109 | Required.
|
110 |
|
111 | This is the path where the package files will be copied to.
|
112 |
|
113 | The path can be absolute or should be relative to the location from which the command is run in the CLI.
|
114 |
|
115 | #### outputLevel
|
116 |
|
117 | Optional
|
118 |
|
119 | This sets the level of CLI logging that is required.
|
120 |
|
121 | Possible values are: ``quiet | normal | verbose``.
|
122 |
|
123 | #### additionalAppuiManifestParameters
|
124 |
|
125 | Optional.
|
126 |
|
127 | This is a key-value collection that can be used to set extra details in the app ( in this case showcase-app ) manifest JSON file.
|
128 |
|
129 | #### additionalProjectManifestParameters
|
130 |
|
131 | Optional.
|
132 |
|
133 | This is a key-value collection that can be used to set extra details in the project manifest JSON file.
|
134 |
|
135 | #### controlSystemHost
|
136 |
|
137 | Required.
|
138 |
|
139 | This should be the hostname or IP address of the device where the package will be deployed.
|
140 |
|
141 | #### promptForCredential
|
142 |
|
143 | This will always be set to true, since the utility will always prompt for the credentials in the CLI.
|
144 |
|
145 | #### sftpDirectory
|
146 |
|
147 | Required.
|
148 |
|
149 | This is the target directory on the ``controlSystemHost``.
|
150 |
|
151 | It must be relative to the SFTP root directory.
|
152 |
|
153 | It will be ``display`` for the showcase-app, or ``HTML`` for CCS.
|
154 |
|
155 | #### deviceType
|
156 |
|
157 | Required.
|
158 |
|
159 | This should be set based on the ``controlSystemHost``, depending on what kind of device you are targeting for the deploy.
|
160 |
|
161 | Possible values are: ``touchscreen | controlsystem | web``.
|
162 |
|
163 | #### contractFile
|
164 |
|
165 | Optional
|
166 |
|
167 | Relative or absolute file path for contract editor config file.File must have .cse2j extension.
|
168 |
|
169 | ## License
|
170 |
|
171 | Copyright (C) 2018 to the present, Crestron Electronics, Inc.
|
172 | All rights reserved.
|
173 | No part of this software may be reproduced in any form, machine
|
174 | or natural, without the express written consent of Crestron Electronics.
|
175 | Use of this source code is subject to the terms of the Crestron Software
|
176 | Development Tools License Agreement under which you licensed this source code.
|
177 |
|
178 | If you did not accept the terms of the license agreement,
|
179 | you are not authorized to use this software. For the terms of the license,
|
180 | please see the license agreement between you and Crestron at http://www.crestron.com/sla.
|