ganeshmurthy commented on a change in pull request #526: mercury initial checkin URL: https://github.com/apache/qpid-dispatch/pull/526#discussion_r299535486
########## File path: tools/mercury/README.md ########## @@ -0,0 +1,508 @@ +# Mercury +##interactive Golang Testing System for Qpid Dispatch Router + + + +<br/> + + +###Requirements + +1. the go language on your machine +2. installed proton and dispatch router software + + + +<br/> + +###Mercury Audience + +Mercury is a tool for developers. The user has one or more installed versions of the Dispatch Router + Proton code and wantsto easily set up a complex network including interior routers, edge routers, and clients with nontrivial addressing patterns. Currently the creation of nontrivial networks is difficult enough that it discourages extensive testing during development. + +Especially Mercury provides a more interactive form of development testing, in which a developer easily creates a network, and easily iterates through a cycle of altering the network, running it, and seeing results from the run. At the end of such a 'session' all of the developer's actions have been captured and will be reproducible later if desired. The captured session is a runnable script, and can be edited and used as a standardized test. + + +<br/> + + + +###The C Client + +The client is written in C to the proactor interface and has been heavily adapted from an original by Alan Conway. It needs to be built before Mercury will be able to do anything useful. Look at the directory mercury/clients, look at the file in there called "m", adapt it for your system, and run it so you get an executable. + +Having Mercury's own client allows it to do things like: + +1. throttle send-speed with the "--throttle" argument +2. Tell the client to form multiple links with multiple "--address" arguments. +3. Tell it where to send its log files and so on. + + +<br/> + + +###Starting Mercury + +The directory from which to run Mercury is also called mercury. So it's mercury/mercury. And an example of a simple run-script is 'example_run_script'. +In that script you will see that it sets an environment variable MERCURY\_ROOT. On your system, please change this to something appropriate to your installation. + + +<br/> + + +###Getting Help + +When Mercury is running, type 'help', and you will see a list of commands with brief descriptions. If you then type "help COMMAND\_NAME" you will get detailed help for that command, plus its arguments. + + + +<br/> + + +###Running the Test Files + + +There is a growing collection of tests scripts in the directory mercury/mercury/tests. They are designed to illustrate different aspects of Mercury. You can run them by using the 'r' script in mercury/mercury and editing it to have the test script you want on the command line, or you can just start Mercury and type "inc tests/05\_addresses" or whatever. + +The test scripts includes one other file with the 'inc' command -- a file called 'versions' which defines two different versions of the router code. + +You will also need to change that 'versions' file to point to one or more versions that you have installed on your system, and then change the 'test' file to only use your versions. (If you only define one version, then it will be the default and will get used whenever you create a new router if you just don't use the 'version' arg in the 'routers' command. + + + + +<br/> + + +###Debugging Startup + +When Mercury starts up a router, it saves all the information you need to reproduce the same startup by hand. The router config file, the environment variables that are set, and the command line that is used are all saved in MERCURY\_ROOT/mercury/sessions/session\_TIMESTAMP/config. Router config files have the same names as their routers. + +Here is an example: + + /home/mick/mercury/mercury/sessions/session\_2019\_03\_05\_2115/config/ + |-- A.conf + |-- B.conf + |-- command_line + |-- environment_variables + + +If you have a router fail to start, or it starts up and is immediately defunct, use this information to reproduce the same startup by hand, and see what's happening. + + + +<br/> + + +###Running a test 'By Hand' + +One nice way to use Mercury is to use it to run a test for you and then see how it did that, so you can run the same setup 'by hand'. You can look in the session/config directory and see all the environment variables it set and the command lines it used for the routers and the clients. + +The command lines for the routers will point to the config files that it created, and those config files have ports that were chosen because they were free at that moment. It is possible that they will *no longer* be free when you run the test 'by hand' if you have other stuff running on your system. But unlikely. + + + +<br/> + + +###Versions + +A 'version' represents a version of the dispatch router + proton code. The idea is that you have as many dispatch+proton installations as you like on your system, you define a Mercury version for each one of them, and then when you create a new router in Mercury you can tell it which version you want that router to use. Mercury will use the executable that corresponds to that version, and make it point to the correct libraries. + +You can define a version in one of two different ways + +1. You can provide the root directories for the proton and dispatch installation, and let Mercury calculate from them all the paths it needs, or + +2. You can directly provide all the paths. This second option is meant for situations where your installation is different somehow from what Mercury expects. + +To define a version with roots, use the 'version\_roots' command something like this: (Here we define two different versions.) + + + version_roots name latest dispatch /home/mick/latest/install/dispatch proton /home/mick/latest/install/proton + version_roots name later dispatch /home/mick/later/install/dispatch proton /home/mick/later/install/proton Review comment: Remove dispatch and proton and just assume that the first is dispatch path and second is proton path ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org For additional commands, e-mail: dev-h...@qpid.apache.org
