Add Custom Components with State Publish

The state publish feature allows you to add private ingredients to your runtimes through the State Tool. In this article we will look at how you can create and upload an ingredient and then update that ingredient.

warning

Ingredients added through state publish may be stored on ActiveState servers. The source code of your components can be removed from our servers upon request. For more information contact support@activestate.com.

Create your ingredient

Create a yaml file

Create a yaml file with the following basic information:

MANDATORY:

• name: The name of the ingredient, as it will appear in the GUI.
• namespace: A private Namespace: private/<Your-Org>/type
• version: The ingredient version.
• dependencies: The builder dependency is mandatory otherwise the ingredient can’t do anything. In the example below, we will use the python-module-builder.

ON INITIAL CREATION ONLY:

• description: A short description of your component.
• authors: Name and email of the code author.

note

If the description is included in your .yaml file when updating your ingredient, that the update will fail.

OPTIONAL:

• features: The feature that this ingredient provides
  • For private ingredients you may need to provide 2 features:
    • The feature matching your name/namespace/version
    • The feature to show where in the build chain this ingredient would fit.
  • In the example below we add a feature of the same name in language/python, which allows other python ingredients to rely on this ingredient if applicable.
• dependencies: These dependencies are required to build the ingredient. This is optional, depending on the needs of your ingredient.

Example:

name: state-publish-update-test
namespace: private/ActiveStateBE/python
version: 1.0.0
description: State Publish Test
authors:
    - name: Ford Prefect
      email: ford.prefect@megadodo.umb
features:
    - name: state-publish-update-test
      namespace: private/ActiveStateBE/python
      version: 1.0.0
    - name: state-publish-update-test
      namespace: language/python
      version: 1.0.0
dependencies:
    - dependency:
        name: python-module-builder
        namespace: builder
        versionRequirements: '>=0'
    - dependency:
        name: python
        namespace: language
        versionRequirements: '>=0'
    - dependency:
        name: setuptools
        namespace: language/python
        versionRequirements: '>=0'
    - dependency:
        name: wheel
        namespace: language/python
        versionRequirements: '>=0'

Publish ingredient

Run state publish with the --meta tag to specify your .yaml file. Provide your source code in a .tar.gz, .zip, or .whl file.

• state publish --meta ingredient.yaml source-1.0.0.tar.gz

note

If your ingredient version changes (for example, v1.0.0 -> v1.0.1), you must add a new ingredient

Build Published ingredient

Checkout the project that you wish to update, and run the following command to build:

state install private/ActiveStateBE/python:state-publish-update-test --ts now

Troubleshooting

To publish a custom ingredient, you have to set the timestamp to the bleeding edge with the --ts tag. To ensure the best chance of build stability at bleeding edge:

• Ensure that your prjoects have been rebuilt recently.
• Ensure that any modules that are subject to change are pinned
• When uploading for the first time, upload into the minimal required project to confirm successful upload and build.

If your upload command is not working add -v to get a detailed error message.

For additional troubleshooting help, contact support@activestate.com.

Final Step - Update Timestamps

Once uploaded, you will need to run any state tool commands that are impacted by your new ingredient with the --ts now flag until the internal timestamp has been updated by an ActiveState engineer. Reach out to ActiveState to schedule a Timestamp update.

Update your ingredient

To update an existing private ingredient of the same version number, do the following:

Create a yaml file

Modify your .yaml file from Phase 1 and do the following:

Remove:

• description
• authors

Modify:

• features if desired
• dependencies if desired

Example:

name: state-publish-update-test
namespace: private/ActiveStateBE/python
version: 1.0.0
features:
    - name: state-publish-update-test
      namespace: private/ActiveStateBE/python
      version: 1.0.0
    - name: state-publish-update-test
      namespace: language/python
      version: 1.0.0
dependencies:
    - dependency:
        name: python-module-builder
        namespace: builder
        versionRequirements: '>=0'
    - dependency:
        name: python
        namespace: language
        versionRequirements: '>=0'
    - dependency:
        name: setuptools
        namespace: language/python
        versionRequirements: '>=0'
    - dependency:
        name: wheel
        namespace: language/python
        versionRequirements: '>=0'

Update ingredient

You will run the same command as before, but with the --edit: tag:

• state publish --edit --meta updated-ingredient.yaml updated-source-1.0.0.tar.gz

You can now modify existing build metadata and change the source tarball associated with this ingredient.

Build Published ingredient

Same as before. Checkout the project that you wish to update, and run the following command to build:

• state install private/ActiveStateBE/python:state-publish-update-test --ts now