ningchaogithub/templatelibrary

Template: a project-template for creating an AX library and generating packages

Apax Template Package

What is a template

See the documentation on custom templates.

How to use it

1. If not done, login to the GitHub registry

   More information you'll find here

2. Create a new library project from template from CLI

   apax create @simatic-ax/library --registry https://npm.pkg.github.com

   and follow the dialog

   alternatively you can add the project name:

   apax create @simatic-ax/library --registry https://npm.pkg.github.com <name of the project>

Create own templates on GitHub

If this template is not suitable for you, you can create your own user specific templates. This describes, how a template for GitHub is created. For other Git provider it might be similar, but each Git provider has its own specific properties.

Setup template workspace

1. Select your target path. In this example, it is shown with the Windows Explorer

   

2. Open a console by entering cmd + Enter in the address text box

   

   Result: A command line window will be opened

3. Create a new, empty template workspace by entering:

   apax create template template-userspecific

   Important: It's very important, that the name of the template package starts with template- followed by the name of the template (e.g. template-userspecific)

4. Open the template workspace with:

   axcode template-userspecific

   Result: AX Code is opened and you an see the following workspace structure which consists of:

   

   1. The apax.yml (1) which is the description for the template package

   2. The apax.yml in the template folder (2) which belongs to the workspace, which will be created, when you create a workspace from this template.

   The template-folder (2) is the folder, which contains all files and folders for the workspace to be created from this template. For example, it can contain:

   • your individual apax.yml with scrips, variables or common used dependencies
   • src- and test-folder with example files
   • a README.md
   • a docs folder for further documentation

Modify the apax.yml (1)

The default apax.yml is not suitable to publish your package on a GitHub registry.

Default apax.yml

name: "template-userspecific"
version: 0.0.0
type: generic

1. Scope of the template on GitHub

   For GitHub it's important, that the scope is part of the name section. On GitHub, the name of your GitHub organization is also the scope.

   If your organization is simatic-ax, then the name section in the apax yml must look like:

   name: "@simatic-ax/template-userspecific"

2. Define URL for the scope @simatic-ax

   Add the registries section to the apax.yml

   registries:
      '@simatic-ax': 'https://npm.pkg.github.com/'

3. Define the content for the template

   In the file section, in the apax.yml, you can define, what generally will be shipped in a package. For templates, at minimum, the template folder must be shipped. This can be done, by adding the following lines to tha apax.yml

   files:
   - 'template'

4. Final apax.yml

   name: '@simatic-ax/template-library'
   version: 0.0.0
   type: lib
   author: Siemens AG
   registries:
     '@simatic-ax': 'https://npm.pkg.github.com/'
   files:
     - 'template'

   In this example, you a template for a library (type: lib) will be crated. A list of valid types, you can find here: valid types

   The author field is optionally

5. Learn More abut the apax.yml

   Manifest (apax.yml) Reference

Prepare GitHub for your template package

1. Go to your organization on GitHub

2. Create a new repository

   

3. Enter exactly the name of your template in the field Repository name. In this example it is template-library and click on Create repository

   

4. Add the remote repository on GitHub to your local repository (optionally)

   git add *
   git commit -m "first commit"
   git branch -M main
   git remote add origin [email protected]:simatic-ax/template-library.git
   git push -u origin main

   Result: now your template is also available on GitHub

Create the template package

Since the repository template-library is available on GitHub, you can continue publishing your package on the GitHub registry.

1. Create the package version

   apax version 0.0.1
   

   Result in apax.yml

   version: 0.0.1

2. Create the template package

   apax pack

   Result: The package file simatic-ax-template-library-0.0.1.apax.tgz has been created

   

3. Publish the package on your GitHub registry

   Important: If not logged in on GitHub, you've to do it before you can publish a package. More information you'll find here

   apax publish --registry https://npm.pkg.github.com --package simatic-ax-template-library-0.0.1.apax.tgz

   alternatively you can add a script publishlib to the apax.yml

   name: '@simatic-ax/template-library'
   version: 0.0.1
   type: lib
   author: Siemens AG
   registries:
   '@simatic-ax': 'https://npm.pkg.github.com/'
   files:
   - 'template'
   scripts:
     publishlib:
       apax publish --registry https://npm.pkg.github.com --package *.apax.tgz

   and call the script with

   apax publishlib

   The template is published and ready to use

Update template

When your template has been changed for any reasons, it is necessary to update the template-package and publish it again. Since it is not possible to overwrite an existing package with the same version on the GitHub package registry, you need to create a new version with:

apax version <new version>

Create a project from your template

1. Go to the folder, where your workspace should be created and open a command line interface (or navigate via command line interface to your destination folder)

2. Enter the command

   apax create @simatic-ax/library --registry https://npm.pkg.github.com

   Note: the when you create a workspace from a template, the prefix template- must not be used.

After this you need to pack and publish the package again (see Create the template package point 2 and 3)

An existing version on the GitHub registry can't be overwritten. If you try it, then apax publish will create an error message.

Learn More

See the documentation on custom templates.