Preface

TMS Smart Setup is already in beta, and we are seeing overwhelming enthusiasm from lots of you. To be 100% honest, way more enthusiasm than what I would have expected for a command-line tool that installs packages. But there is also one recurring concern we've noticed, and that's the reason I am writing this post. The specific questions and wording vary, but I think the root of the question that you are asking is: "Will this tool take control?"

And it is a valid question. We have two categories of helpers in software: "tools" and "frameworks". It may not be the exact definitions, but in my mind (what matters for this post), a tool is something that helps you do a thing. It is a lawyer that helps you do your taxes. You ask him to do some particular things, but you are still the one doing the taxes. On the other side, we define a framework as something that takes control: It is a company that takes care of your taxes and only asks you to sign papers when required. They do the job, and they ask you questions when they need to. 

It happens everywhere: for example, you can parse XML using a SAX parser or a Pull parser. SAX "takes control": you give it the file, it processes it, and it asks you what to do with the nodes as it reads them. It does the job and asks you the questions. A pull parser is a helper: You ask it what the next node in the xml file is, and it gives it to you. You do the job and ask the tool for help in the complex parts.

We personally prefer tools over frameworks, and that's mostly what TMS does. We like selling hammers, not hammer-factories. So, to answer the question: Smart Setup is a tool, not a framework. It will help you when you need it, but you might not want to use it at all, or only use it for some tasks, and do the others yourself. All cases are supported. This is not an iTunes-like app that will take control over your components and only work if you follow its conventions, and once you are using it, you better not touch anything manually because you will break the app. Smart Setup does have some conventions it needs, but they are minimal. It is designed to help with what you might already have, not to take control. And in the rest of this post, I'd like to discuss exactly what it does, so you can feel more confident using it. Better documentation is coming (when we get the time), but I wanted to get started here.

Actions

At the core, Smart Setup does two things: Fetch and Build.

1. Fetch: This action does 4 things:

     1.1. It downloads smart setup bundles from our site.

     1.2. It saves them to a "Downloads\CurrentVersions" folder, sending older versions to "Downloads\OldVersions"

     1.3. It unzips the bundles under a "Products" folder:

     1.4. It saves a file: "tmsfetch.info.txt", at the root of the unzipped folder. This file tells SmartSetup that this bundle is managed by it. Because you might have your own components inside Products, and we won't touch them unless it was us who put them there. Also, deleting tmsfetch.info.txt from the folder will make fetch "stop managing" this component. For example, in my test machine here I have 2 components: TMS FlexCel and TMS UI Pack. I deleted tmsfetch.info.txt so I can work with FlexCel on my own, without worrying about tms fetch overwriting it with newer versions. When I do a `tms list` command, FlexCel will appear with a "*" because it isn't managed:

That's all the command `tms fetch` does. Downloads a zip and unzips it. Note that the "smart setup bundles" are just zip files with source code inside and a "tmsbuild.yaml" file that tells `tms build` how to build and install the component.

2. Build: This is the action that compiles and registers the components in the IDE. It is completely independent from the "Fetch" command above, and you can always use one and not the other.

As said, `tms build` doesn't care about the fetching part or how the components arrived in the folder. It won't care if there is a tmsfetch.info.txt there or not. It will just look at all the folders below it, searching for tmsbuild.yaml files, and when it finds them, follow the instructions on them, and compile the components. The Fetch action above will put all the products it downloads into a "Products" folder, but you can put your own components wherever you want and have `tms build` build them. Build doesn't know about a "Products" folder at all.

And that's it. You can combine both actions in any way you like. You might, for example, call `tms fetch` in one machine with internet access, and then copy them to a server without internet, unzip them inside some folder, and use `tms build` in this server to install them. You might not use `tms build` at all, just `tms fetch` and then unzip the files and install them manually. Or you might use `tms build` alone, to build your own components or components you downloaded from our site. Smart setup already comes with some prepackaged actions that we think will prove useful on their own, but they are all combinations of Fetch and Build.

  * `tms install product`: Fetches "product" from our side, then Builds.

  * `tms uninstall product`: Deletes "product" from the "Products" folder, then Builds. (when `tms build` detects a folder was removed from the ones it was building, it will automatically uninstall it from the IDE)

  * `tms update`: Fetches new versions of installed products, and if there are any, then Builds.

Folder Structure

Below is the folder structure used by Smart Setup. I wanted to document them all, not because you need to know about them, but because this is a "How it works" post, and I want you to be confident that there are no magic or critical folders which if you delete, smart setup will stop working.

• Root: The root folder where Smart Setup will operate. It might or might not contain a tms.config.yaml file. If it contains it, smart setup will use it to configure its behavior. If the file doesn't exist, Smart Setup will use a default configuration which can be altered by command line parameters. You can create this file if it doesn't exist and edit it by typing `tms config`.
•  Root\.tmssetup: This contains the metadata for Smart Setup. You shouldn't need to look inside it, but again, this is "how it works" so we will peek anyway. 
• Root\.tmssetup\build\bpl:  Here we put all the bpls of all the components, so Rad Studio can find them. This folder is added to the Windows Path. The bpls also exist in the "Products" folder where they are compiled, but they are hard-linked here so we need to add a single entry to the Windows Path, not one per product.
• Root\.tmssetup\build\hashes: This is information `tms build` stores about the products it compiled successfully, so it knows what it has to recompile. If you removed this folder, `tms build` would just assume nothing is compiled and recompile everything. In fact, when you type `tms build -full`, that is exactly what the command does. It removes the hashes folder, then builds.
• Root\.tmssetup\build\uninstall: This folder contains information about how to uninstall what `tms build` installed. As this information is here and not in "Products", this means you can nuke a product from "Products", run `tms build` and it will uninstall it with the information in this folder. As explained, this is exactly what `tms uninstall` does. This might be the only folder you can't remove at will. But still, if you removed it, `tms build` will just fail to uninstall the components. If you deleted this folder by mistake, you could reinstall all the products again, and then you will be able to uninstall them.
• Root\.tmssetup\fetch\credentials: This file contains your tms registration information so `tms fetch` can download the products you own. If you deleted this file, you would have to type `tms credentials` again to recreate it. Also note that this file is only for fetching components from our servers, you can still use `tms build` without any credentials.
• Root\Downloads\CurrentVersions: Here is where `tms fetch` downloads the latest product bundles. As explained before, those product bundles are just zip files with the source code inside.
• Root\Downloads\OldVersions: This is a backup of older versions of components. Whenever you get a newer version of a component, if goes to CurrentVersions above, and the previous last version is moved here. In the smart setup config file (the one you can create or edit with `tms config`), you can specify how many versions of old components to keep. By default, Smart Setup will keep them all, but you might want to say only keep the last 3 versions and remove anything older. Keeping 0 versions will remove the downloads even from the folder Root\Downloads\CurrentVersions above. You might use this option if in a server and you have a backup somewhere else.
• Root\Products: Here is where `tms fetch` will unzip the bundles in Root\Downloads\CurrentVersions. You can remove any folder in here, and when you rerun `tms build` it will uninstall them. You can also remove the file tmsfetch.info.txt and `tms fetch` will stop managing this component, so it will not update it further. And once again, this is a folder that is only special for `tms fetch`. `tms build` doesn't know anything about any "Products" folder, so you can put other component made by you in other folders under root that are not "Products". We recommend that you leave the "Products" folder to those components managed by `tms fetch`.
• Root\Temp: Many types of temporary files that we need to create when fetching or building. You can remove this folder at any time, there is nothing important there. In fact, Smart Setup will try to delete all files inside it every time you start it.
• Root\Logs: The troubleshooting files that you will need to send us if there are any issues that you can't solve. Those files contain a history of all the actions `tms build` and `tms fetch` performed, so they can help us figure out what went wrong. Of course, there is no personal information that we purposedly include in the logs (but if you named your root folder with your Credit Card number and secret code, well, there might be). It is just a log of what happens to help us troubleshooting. But the files are plain text, so you can review them before sending them.

Note that this is all in beta and this is still changing, but this is "how it works" today. It isn't likely to change soon, but you never know. But the main thing I wanted to transmit is that from the start, Smart Setup was designed to leave the control to you, who is the one who should have it. Smart Setup will help you as much as you want, but not more. In the worse scenario, you could just use the zip bundles with the source code and do everything manually. Which is something you can't do today with our current .exe installers.