Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 150 lines (100 sloc) 4.572 kb
ce6edad @rustyio Add startup message. Update README.md.
authored
1 # Stay in Sync
2
f33600b @rustyio Update readme.
authored
3 ## What is Sync?
ce6edad @rustyio Add startup message. Update README.md.
authored
4
f33600b @rustyio Update readme.
authored
5 Sync is a developer utility. It recompiles and reloads your Erlang
6 code on-the-fly. With Sync, you can code without friction.
ce6edad @rustyio Add startup message. Update README.md.
authored
7
f33600b @rustyio Update readme.
authored
8 ![Successful compilation image.](http://rusty.io.s3.amazonaws.com/sync/sync_01.png)
9
10 What does "code without friction" mean? It means that with Sync
11 running, you no longer need to worry about running `make`, or
12 `c:l(Module)` again. Just write code, save the file, and watch as
13 Erlang automatically detects your changes, recompiles the code, and
14 reloads the module.
15
16 ## How can I use Sync?
ce6edad @rustyio Add startup message. Update README.md.
authored
17
18 The recommended approach is to put sync in your $ERL_LIBS directory.
19
18e4147 @rustyio Add patching feature, allow sync to distribute updated modules across a ...
authored
20 ```bash
21 cd $ERL_LIBS
22 git clone git@github.com:rustyio/sync.git
23 (cd sync; make)
24 ```
ce6edad @rustyio Add startup message. Update README.md.
authored
25
f33600b @rustyio Update readme.
authored
26 Then, go in the Erlang console of an application you are developing,
27 run `sync:go().`. You can also start sync using
28 `application:start(sync).`
ce6edad @rustyio Add startup message. Update README.md.
authored
29
f33600b @rustyio Update readme.
authored
30 Starting up:
ce6edad @rustyio Add startup message. Update README.md.
authored
31
f33600b @rustyio Update readme.
authored
32 ```txt
33 (rustyio@127.0.0.1)6> sync:go().
ce6edad @rustyio Add startup message. Update README.md.
authored
34
f33600b @rustyio Update readme.
authored
35 Starting Sync (Automatic Code Compiler / Reloader)
36 Scanning source files...
37 ok
38 08:34:18.609 [info] Application sync started on node 'rustyio@127.0.0.1'
39 ```
ce6edad @rustyio Add startup message. Update README.md.
authored
40
f33600b @rustyio Update readme.
authored
41 Successfully recompiling a module:
ce6edad @rustyio Add startup message. Update README.md.
authored
42
f33600b @rustyio Update readme.
authored
43 ```txt
44 08:34:43.255 [info] /Code/Webmachine/src/webmachine_dispatcher.erl:0: Recompiled.
45 08:34:43.265 [info] webmachine_dispatcher: Reloaded! (Beam changed.)
46 ```
b159a83 @choptastic update sync_utils:get_src_dir to include a Nitrogen mode, which keeps it...
choptastic authored
47
f33600b @rustyio Update readme.
authored
48 Warnings:
b159a83 @choptastic update sync_utils:get_src_dir to include a Nitrogen mode, which keeps it...
choptastic authored
49
18e4147 @rustyio Add patching feature, allow sync to distribute updated modules across a ...
authored
50 ```txt
f33600b @rustyio Update readme.
authored
51 08:35:06.660 [info] /Code/Webmachine/src/webmachine_dispatcher.erl:33: Warning: function dispatch/3 is unused
18e4147 @rustyio Add patching feature, allow sync to distribute updated modules across a ...
authored
52 ```
b159a83 @choptastic update sync_utils:get_src_dir to include a Nitrogen mode, which keeps it...
choptastic authored
53
f33600b @rustyio Update readme.
authored
54 Errors:
55
56 ```txt
57 08:35:16.881 [info] /Code/Webmachine/src/webmachine_dispatcher.erl:196: Error: function reconstitute/1 undefined
58 /Code/Webmachine/src/webmachine_dispatcher.erl:250: Error: syntax error before: reconstitute
59 ```
b159a83 @choptastic update sync_utils:get_src_dir to include a Nitrogen mode, which keeps it...
choptastic authored
60
ce6edad @rustyio Add startup message. Update README.md.
authored
61 ## Growl Notifications
62
f33600b @rustyio Update readme.
authored
63 If you are running a Mac and have [Growl](http://growl.info) and the
64 **growlnotify** utility installed, Sync will pop up Growl
65 notifications with compilation results. This will also work on Linux
66 if you have **notify-send** (Fedora: `libnotify` package, Ubuntu:
67 `libnotify-bin` package):
ce6edad @rustyio Add startup message. Update README.md.
authored
68
69 Successful compilation:
70
71 ![Successful compilation image.](http://rusty.io.s3.amazonaws.com/sync/sync_01.png)
72
73 Warnings:
74
75 ![Compilation warnings image.](http://rusty.io.s3.amazonaws.com/sync/sync_02.png)
76
77 Errors:
78
79 ![Compilation errors image.](http://rusty.io.s3.amazonaws.com/sync/sync_03.png)
b6f019e @rustyio First commit.
authored
80
4448dd5 @choptastic Update readme with growl notification enabling/disabling.
choptastic authored
81 ### Disabling Growl Notifications
b6f019e @rustyio First commit.
authored
82
f33600b @rustyio Update readme.
authored
83 If you find the Growl/notify-send notifications annoying, you can
84 choose to disable them with two ways:
aaf4e45 @rustyio Convert to an application, automatically compile and reload changed modu...
authored
85
fbefe1c @choptastic readme updated to be a little more accurate
choptastic authored
86 #### 1. As an environment variable called from the erlang command line:
4448dd5 @choptastic Update readme with growl notification enabling/disabling.
choptastic authored
87
fbefe1c @choptastic readme updated to be a little more accurate
choptastic authored
88 erl -sync growl false
89 erl -sync growl true #this is the default
18e4147 @rustyio Add patching feature, allow sync to distribute updated modules across a ...
authored
90
4448dd5 @choptastic Update readme with growl notification enabling/disabling.
choptastic authored
91
fbefe1c @choptastic readme updated to be a little more accurate
choptastic authored
92 #### 2. From within the Erlang shell:
4448dd5 @choptastic Update readme with growl notification enabling/disabling.
choptastic authored
93
94 sync:growl(true). % Enable notifications
18e4147 @rustyio Add patching feature, allow sync to distribute updated modules across a ...
authored
95 sync:growl(false). % Disable notifications
96
97 ## Remote Server "Patching"
98
99 If you are developing an application that runs on an Erlang cluster,
100 you may need to recompile a module on one node, and then broadcast the
101 changed module to other nodes. Sync helps you do that with a feature
102 called "patching."
103
104 To use the patching feature:
105
106 1. Connect to any machine in your cluster via distributed
107 erlang. A simple `net_adm:ping(Node)` should suffice.
108
109 2. Run `sync:patch()`. This will start the Sync application if it's not
110 already started, and enable "patch mode".
111
112 3. Start editing code.
113
114 Sync will detect changes to code, recompile your modules, and then
115 sent the updated modules to every Erlang node connected to your
116 cluster. If the module already exists on the node, then it will be
117 overwritten on disk with the new .beam file and reloaded. If the
118 module doesn't exist on the new node, then it is simply updated in
119 memory.
120
f33600b @rustyio Update readme.
authored
121 ## How does Sync work?
122
123 Upon startup, Sync gathers information about loaded modules, ebin
124 directories, source files, compilation options, etc.
125
126 Sync then periodically checks the last modified date of source
127 files. If a file has changed since the last scan, then Sync
128 automatically recompiles the module using the previous set of
129 compilation options. If compilation was successful, it loads the
130 updated module. Otherwise, it prints compilation errors to the
131 console.
132
133 Sync also periodically checks the last modified date of any beam
134 files, and automatically reloads the file if it has changed.
135
136 The scanning process adds 1% to 2% CPU load on a running Erlang
137 VM. Much care has been taken to keep this low. Shouldn't have to say
138 this, but this is for development mode only, don't run it in
139 production.
140
141 ## Using Sync with the Nitrogen Web Framework
142
143 If you are running sync with the [Nitrogen Web Framework](http://www.nitrogenproject.com), be sure to add the following line to your etc/vm.args file:
144
145 ```txt
146 -sync sync_mode nitrogen
147 ```
148
149
Something went wrong with that request. Please try again.