Correct way to use deploy and/or active project

Hi all,

I am not an experienced perl user, and I am doubly not an experienced ActiveState perl user…

I do have some experience deploying packages and languages to machines however.

My problem is: I cannot work out what the intended usage is for projects and deployments.

The history is:

  • I an resurrecting an old C++ build process that used to run using now obsolete OS/tools/SDKs etc
  • that used an earlier version of ActiveState perl and installed it by running an installer checked-in to the depot
  • I started looking into using a newer version of perl and got stuck as the way of installing packages suggested on the web-site seemed very cumbersome and awkward… not least because the wizard knew nothing of some of the packages I needed… (I subsequently found another bit of UI that did know about those packages but that wasn’t well advertised.)
  • after some head scratching I discovered “state install XXX” and that was good
  • and that prompted me to “push” and “activate” the project…
  • however newly installed packages frequently did not seem to be accessible to other processes on my system, it looked as if those processes were still accessing the default project (although running “state show” for them claimed they were not…)
  • THEN I discovered “state deploy” and that seemed to fix that, skipping whatever was going wrong with project configuration/caching and creating a folder with the installed packages explicitly copied into it…
  • (although my install cycle is now: state install XXX; state push; state deploy AAA/BBB – and this duplicated the folder entries in the path every time I ran it, requiring me to do manual clean-up, which is a pain and should be something the gets right itself… the concept of “deployment” usually comes with a assumption of idempotency so that it can be repeated to get incremental changes…)

So far, so good, my investigation moved on…

HOWEVER, now I have had cause to nuke that copy of the depot and make a fresh one (basically wanting to see how it behaves without some other changes I made) and I have encountered something I cannot quite get my head around…

  • when I type “perl” it tells me it “cannot find the project file” and it cites the (now nuked) location where the project was before I started “deploying” it elsewhere…
  • (I do not have that project’s folder anywhere in any paths anymore)
  • I wondered if maybe, now I was deploying, I did not need an activate project? But there does not seem to be any way to deactivate it…
  • I also hypothesized that I only needed the activated project to push from and that what I was doing with my install/push/deploy cycle was: 1) updating a project I was not actually running, 2) pushing that, 3) deploying to back to the location where it was run from – which I imagine should not be necessary but works.

So my question is How should I be using this. The situation is that I will configure this on my machine but, when others join the project, they will need to get the same configuration as I have. I was imagining we could do that by telling them to deploy the same project I was (or even just check-in the deployed folder, tying the versioning together in a very desirable manner). However, if they need an “activated” project as well as the “deployed” one I am not sure where that leaves us…

I have not, as yet, been able to switch the “activated” project to the same folder as the “deployed” one… and I am unsure whether this 1) makes no sense, or 2) would make sense but cannot get past the missing project folder (I can put that back, but I am still trying to understand what should be happening…)

I have looked for online help on this, but I’m finding things that say “this is how you activate” without explaining exactly what it is for, or how it interacts with deployment.

Any info/links/suggestions gratefully received.



Hi @IanBadcoe ! Thanks for the very detailed explanation – you’re actually totally right in that your explanation:

The situation is that I will configure this on my machine but, when others join the project, they will need to get the same configuration as I have. I was imagining we could do that by telling them to deploy the same project I was

Is totally correct – there’s just a few details I think that are dependent on your exact configuration. So in general, to achieve the above, what you would do is:

  • Create a project – normally as you found out, you start from the Web UI. You can then add the packages you want either via the web UI or via state install. The reason you want to create a project is that it creates a shared source of truth for what your configuration is amongst your team members. It’s also revisioned so that it’s always reproducible.

  • Anyone who wants to use that configuration simply activates the project, by typing state activate myOrg/myProject – this will install everything you set up in your project on their machine. Now, here’s where I think there might be confusion – unlike “installing” Perl on your machine via an installer, what activate does, is it sets up a virtual environment–like a sandbox that is a totally self-contained Perl installation. This means that if you want to switch projects to another Perl with a different set of packages, you can easily do so just by “activating” a new project. It’s also worth nothing that the project is only “activated” within the shell that you’re currently running, so if you have other processes that need to access Perl, that’s where deploy comes in.

  • If you need a sort of classic “installation” of Perl that can be globally accessed on your machine by other processes, etc. then you can use state deploy and this will basically “install” Perl on your machine. You might need to setup some PATH variables to point it at the installation like PERL5LIB, and add the location where you deployed it to your PATH so that it can find perl.exe, etc. But once deployed you do NOT need to activate.

  • The other thing you mention is state push – so, if you’re familiar with git – this is the same concept. When you run state install – any changes you’re making are ONLY on your local machine. If you want to “push” them to the platform (at which point they’re shared with all your team members), then you run state push and it will push those to the platform.

Hope that helps clarify some of the concepts used on the platform – happy to explain more if there are other questions.

1 Like

Hi Pete,

Thanks you, that is clear, however I think there are some other complexities going on.

A thing I forgot to mention in my original explanation is I also tried “state activate IanBadcoe/perl --default” which looked as if it should make the project universal across the whole machine? After doing that things looked confused and other processes (even after a reboot) reported being set to my project but could not find the recently installed modules… when I looked at the @INC value reported in the errors, it was using a cache folder dated back when I first installed Perl, instead of the newer one which (I presume) went with the current project.

Because in this case there are a large number of scripts/vc-projects/configuration files etc etc, any one of which might invoke perl, I cannot practically add a “state activate” to every place where it might happen, so from that point of view I think deploy is the way to go (unless “activate --default” effectively has the same effect – but, as I said, it seemed inconsistent when I tried that…)

I am also not sure how to handle things if I have an activated and a deployed project on my system (is this a bad state to be in, or an expected use case?). Because of the history I followed (with “activate --default” AND “deploy”) I think this is the state I find myself in. I had been assuming that the deployed copy completely took over from the activated one, but the current error about not being able to find the project folder implies otherwise… (and I have not found how to remove a default activation.)

Thanks again, this is clearer, and I think deploy is the way to go for other users, but I am still a little uncertain how to resolve the situation I have on my machine where I am running installs/pushes as well as consuming the deployment…



Thanks for the additional info @IanBadcoe – it sounds like there might be a bug with the --default parameter as it should behave the way you expect where it’s effectively the same as a deploy, but with the added benefit that it’s easier to keep updated compared to the deployment (which you’d have to re-deploy each time you made a change to the master project). Let me file an issue for the --default problem with the dev team here as your INC folder should definitely be updated.

1 Like

Thank you!

I think it all makes sense now…

I was seeing what I thought was another bug, where when I redeployed it retained some obsolete paths from the previous deployment in PATH, but I have realised that was because the folder where I was deploying was not empty, and had previously been configured from a different location (there are some symbolic links involved in the depot configuration). Once I wiped the folder, the paths came up correctly… so I think that is odd behaviour (since the deployment knows where it now is and could presumably therefore get it right) but arguably encountering this is user error rather than a bug.

I think this sorts me out, thanks! I will have to continue the install->push->deploy cycle, which is not quite as convenient as “activate --default”, but I can get by.

Thanks again,


Thanks for these instructions. Your website should have a link to these instructions and explanation in the download section for each project. Not sure why you are not doing that even though I see plenty of confused people in these forums

That’s exactly what I want. When I ran ‘state deploy,’ I received the following message:

The following argument is required:
Description: The namespace of the project that you wish to deploy

I have no idea what this means. Does choosing an org/project “namespace” have filesystem implications? Where can a long-time user of ppm get a description of the new project concept that would make it possible to use newer versions of Perl in the way that I’ve used it for 20 years? Thanks.

Hi there @Shinelikethunder – so, as part of the onboarding process you will have created a project on the platform that contains the list of packages that you need. That is contained within an “organization” on the platform (usually just your username), so that’s the minimum you need, however if you want to deploy it to a specific location you can use the --path flag to specify a particular location.

I’ll note that using “deploy” is not the recommended or preferred way to manage your Perl runtime installation because it is harder to keep up to date, and you can’t use the CLI to install to it the way you would’ve used PPM in the past.

But, if you need a kind of “classic” install, you run something like:

state deploy myOrg/myProject --path path/to/where/you/want/it

…you can always type state deploy --help to get detailed help on how to use the tool.

An alternative method is to use state activate myorg/myproject --default which will still utilize the virtual environment functionality, and let you use state install package name in the exact way that you used ppm in the past. This would be preferred over using the deploy method – really there are only a few specific use cases that should require a deploy.

Hi Pete,

I think I’m starting to understand. Does a “project” replace what was previously a Perl installation and site library? What is “the onboarding process?” Is that part of the installation process for newer Perl versions? Does (should) my own package library become part of the project, or is it separate? It sounds like I really just want to create a single project and not “deploy” it at all, and that I can then somehow install that same project on other machines to reproduce the same environment; is this correct? Thanks.

Hi @Shinelikethunder – that’s a good way to think about it, a Project represents all the bits that were contained within a site installation under the previous model. The difference now is that you can easily have multiple “Projects” installed on your machine and switch between them seamlessly using the activate command.

When I refer to onboarding process, I just meant the screen flow when you signed up for an account, it takes you through creating a project/adding packages etc.

Your own package library does not become part of the project (eg. there’s no way to upload your own modules to the system) – so what you have in the project is just the “runtime” pieces needed to make your code run. However, you can link a GitHub repo to your project on the platform (in settings) and that will automatically clone it whenever you activate the project, meaning you can get your runtime and your own code in one command.

But exactly, the idea is that you can easily reproduce your exact runtime environment along with all your code easily on any machine. Imagine you had a new person joining your team and you needed them to get Perl and all the required modules set up and configured, if you had your GitHub repo linked to your platform project, you could just say state activate myOrg/myProject and then boom, it would install everything. You can even create automation within that sequence to run tests or do other environment configuration.

But that’s the “idea” behind having this model under the new system. Hope that helps!

OK, I see it now. I’ve had an account for years, but hadn’t signed in for a long time. It gave me an option to create a project, which I did. However, it didn’t give me an option for where to put the project. I have a few questions before I start installing modules. Thanks for all of your help!

  1. The project folder was created on a slow HDD instead of the SSD that C: is on. What will be placed in the project folder other than activestate.yaml? I see that the project folder appears in environment variables. How do I move the project if I want to?
  2. There’s a warning about needing to rename the ‘ppm’ script; Is this the ‘ppm’ file in the Perl 5.20.2 install folder?
  3. When I open a new command prompt, it’s still using version 5.20.2. How do I fix this?
  4. I don’t see Perl 5.34 listed in my installed apps and can’t find its executables. I find a perl.bat in the PATH. Why is this?
  5. Due to a bug in Win32::RunAsAdmin that mangles ARGV, I have scripts that explicitly execute perl.exe in an elevated command window. Is this still going to work, or do they need to be rewritten?

1). The Project folder is just the config files. You could state clean the project and state activate it again into a different folder if you want to move it.
2). No. That PPM file is obsolete. PPM doesn’t actually work with any builds created on The Platform and if it’s present it is a shim provided by The State Tool (state install).
3.) state activate from within the project folder. State activate is not persistent and does not apply to other users. The old Perl is still on PATH, and will be used if state activate hasn’t put a newer version ahead of it.
4). state activate isn’t an installer. It will not make any global changes or changes to the registry. Neither with state deploy. state activate places all the Perl files in a cache file tree under your AppData folder, and perl.bat is a shim that manages locating it.
5). The administrator user does not have access to the the AppData folder in a user area. You might be able to state deploy and have the administrator user set up with appropriate env variables instead.

I don’t fully understand 3-5, but my sense is that this isn’t a model suitable for those of us who routinely open a command prompt in a folder and run Perl scripts there to generate reports. Can I put %localappdata%\activestate\cache\03eece75\exec in the path permanently? What would be the downside of doing so? Thanks.

Mostly that would depend on how you’re used to running those Perl scripts. If you’re depending on doubleclicking the script and letting the registry entries for .pl files handle starting and feeding your script to a Perl interpreter, no it won’t. A full MSI or EXE format installer will set the registry entries up like that. A Perl installed into AppData won’t work that way because it’s not available to all users.

But if you’re using
perl arg1 arg2
format from the command line, it absolutely will and will allow things like having multiple versions of Perl installed without conflicting so you can see how each version of Perl deals with your scripts. You state activate to switch between the versions you want to try out, and someone else can state activate a different version with their own userID, or have the old 5.20 version that was installed globally with an MSI.

I run my scripts by shift-right-click on the desired working folder, then typing ‘perl arg1 arg2’. This doesn’t execute the new version of Perl after running ‘state activate’ in a different cmd window. It sounds like when I want to execute a Perl script, I need to shift-right-click on the Project folder, run ‘state activate,’ then ‘cd’ to the desired working folder before running a script.

The behavior of “shift-right-click” is determined by the window manager you’re in, so if you’re in an IDE it could be different from what the Windows file manager does.

You’re starting a fresh command line with that process, so the current settings in another window don’t apply to it. If you do as you describe, running state activate after you open the new window, you would have the new Perl.

If you’re comfortable with that, you might look at using the --default option for state activate, which sets up the batch file so that a default project can be used when you are not currently in a project folder. That should allow you to skip the step of changing to the Perl project folder before you activate.

That seems to cd to the project folder from the folder that I run ‘state activate’ in. It doesn’t even pushd so that I can get back. And who wants the project name and Perl version in every command prompt? Not ready for prime time.